What are Webhooks?
Imagine you work at a pizza restaurant with frequent supply problems. Your boss has instructed you to check the pantry every hour to avoid running out of ingredients — a process that is both error-prone and labor-intensive. There must be a better way! Some time later, the cook, noticing your plight, offers to call you whenever they notice any ingredient running low. Now, instead of constantly checking the pantry, you simply wait for your cook’s message.
In this example, the cook represents a webhook, and an ingredient running out represents an event. Webhooks are a powerful tool that allow you to stay up-to-date with events triggered by your users as they move through our inquiry flow. This provides increased visibility and control by allowing you to automatically react to user actions. With webhooks, you no longer need to keep checking with us to stay on top of things — we'll tell you directly!
Webhooks allow you to subscribe to your customers’ actions as they proceed through the Persona inquiry flow. Whenever a subscribed event occurs, your webhook will automatically notify you by sending a message to the URL registered with the webhook. For the full list of events, checkout this events page in our documentation.
How to get started
- First, click the “create webhook” button on the top right corner of the Webhooks page in the Dashboard. That will bring you to this screen below, where you can input your specified URL, select your desired environment (sandbox or production) and select the events that you want to subscribe to.
- Once created, your new webhook will be visible as a table row. By clicking into the row, you can see several descriptors about your webhook.
Webhooks can be edited directly from the table view by opening the context menu on the right end of the row, or from the detail view in the top right corner of the page. Both the URL and the list of subscribed events can be edited. Note that editing the webhook will affect when new events are triggered but will not retroactively affect existing webhook events.
Additionally, if a webhook is no longer useful, you can turn it off by clicking ‘Deactivate’ either from the webhook header or the context menu (that dropdown menu with the three horizontal dots on the main Webhooks page).
Debugging with Webhooks
If your system is not receiving the messages you’re expecting, you can troubleshoot by examining our webhook event logs, which act as a record for all webhook triggers. From the events view, you can see all webhook events that were triggered by an event and can link to the webhook that fired the webhook event. Similarly, you can see all webhook events fired by a webhook from the webhook view and view the event that triggered the message. This can ease debugging by acting as an audit trail that you can check from both sides.
If you’re having trouble, our team is always here to help — just message [email protected].
Validating Webhook events
Imagine you have a referral system in place that gives a payout every time a user refers a certain number of friends. An attacker could repeatedly send "User X referred a new customer" messages to your system in an attempt to collect multiple payouts.
To avoid this, all webhooks have an associated secret key that is known only to you and to Persona. Whenever a webhook event is created, Persona uses the secret key to cryptographically sign the message, which authenticates the message as originating from us. By examining the signature, you can distinguish authentic messages sent by Persona from fraudulent messages sent by potential attackers.
Keep the secret key safe! The secret key must be kept private because if leaked, attackers will be able to produce verified signatures, and it will be difficult to distinguish these messages from authentic ones. You can view or regenerate your secret key at any time in the Dashboard.
Webhooks out in the wild
There are many ways you can use webhooks with Persona — the possibilities are endless. But to narrow it down, here are some popular use cases.
- To trigger an email when an inquiry completes. This means you can receive an email notification of the events you have selected in the Webhook configuration to get updates, rather than needing to log into your Dashboard. An easy way to do this is by using Zapier with Persona’s hosted flow. If this sounds interesting or relevant to you, check out our Help Center to get started.
- To trigger a Slack message, or any other type of notification, when your prescribed events fire. An easy step-by-step guide on configuring Webhooks for Slack notifications is also conveniently in the Help Center.
- To keep end-user PII (personal identifiable information) up to date by sending you event completion notifications when information is updated.
- To send text or email reminders to individuals who don’t complete the flow. For this, you can set up a webhook to trigger the inquiry expired event and automate a notification to your users.
- To automatically keep records up to date. When an inquiry is approved or declined, you can use a webhook to update the individual’s records in your internal support dashboard or database.
If you want to start playing with Webhooks but you don’t have an endpoint or your backend isn’t set up yet, try using a testing tool like webhook.site. It will instantly set up a webhook endpoint that you can immediately use in your Persona Dashboard.
Ready to get started? Check out our Webhooks documentation for more information, or go directly to the Webhooks page in the Dashboard.
Don’t have an account? It shouldn’t be too hard to fix that. You can try playing with our webhooks in a sandbox environment or reach out to [email protected]
