Webhooks are a great way to improve integrations between sites and services. They allow for an automated way to keep separate systems up-to-date about what might be going on. Vanilla's Webhooks addon can allow you to receive automated notifications of key events on a site, like user registrations or new comments.
To use webhooks, you first need to understand what they are and what they do. Many have written some great posts on the topic, so here's some recommended reading before getting started:
Setup
Once the Webhooks addon has been enabled, a new "Webhooks" sidebar item should be available under the "Technical" heading on the "Settings" tab of the dashboard. Clicking this will take you to a list of webhooks configured for the site.
Adding a Webhook
Clicking "Add Webhook" from the list will display a simple form with five configurable elements:
- Name is a user-friendly name for this webhook. It is only used in the UI and does not have any direct impact on functionality otherwise. Just choose something that makes sense for you, particularly if you ultimately have multiple webhooks configured.
- Delivery Url should be the full URL to an external URL that will act as the webhook endpoint. This is where configured events will be delivered. It is important this URL be correct and accessible from Vanilla's servers.
- Secret will contain a private, secure value that is used for signing each event. This signature is how you can be confident the event originated from Vanilla. That is why it is important this value be cryptographically-secure and never disclosed to untrusted parties.
- You may configure whether your webhook should receive all available event types in Vanilla or only a subset. For example, if you're specifically interested in registrations, toggle on "select individual events" and ensure "Users" is the only box checked.
- The Active toggle determines whether or not events will be sent to a webhook. You can safely activate and deactivate a webhook without losing its configuration.
Once you've configured your webhook, click "Save" to create the entry and you're all set.
Editing a Webhook
Once you have at least one webhook configured, you'll see it displayed in the list. Should you need to adjust a webhook, you can click the edit icon, a pencil, on its row. This will deliver you to the same form seen when adding a new webhook, except the fields will be pre-populated with the configured values.
Deleting a Webhook
Each webhook row also contains a "Delete" icon, a trashcan. Clicking this will initiate deletion of the webhook configuration. Confirmation is required. If the action is confirmed, the webhook configuration will be deleted. All associated data will be irrecoverably lost.
Disabling a webhook may be a more suitable alternative than deleting it.
Recent Deliveries
Each row in the list of webhooks contains a "Recent Deliveries" icon, a clock, that takes you to the recent event delivery records for that webhook. They will be arranged in a table containing four columns:
- Delivery ID is a globally-unique identifier for the delivery attempt. These are generated at the time of the request.
- The Date when the delivery was initiated.
- Duration indicates the time, in seconds, between when the request was initiated and when a response was received to complete it.
- A Status code of the HTTP response, if available. Error codes will be highlighted in red.
A clickable chevron icon will also be present at the start of each row, alongside Delivery ID. When clicked, additional details about the delivery will be displayed. Specifically, the raw headers and body contents of each request and response, if available, are expanded.
Currently, only the most-recent fifty deliveries are displayed. They are listed by Date in descending order.
Signing
One of the most important parts of securing your webhooks integration is verifying signatures. Every webhook delivery sent by Vanilla will include a X-Vanilla-Signature header. This header contains two key things: the algorithm used to generate the signature and the signature, itself. Vanilla currently uses the SHA-1 algorithm to generate a hash-based message authentication code (HMAC) using the webhook's configured Secret. When receiving an event from Vanilla, it is crucial to generate a signature on your own, using the same parameters and the body of the request as the "message" data, and compare it against the X-Vanilla-Signature header. If the signatures do not match, the event should not be trusted.
Troubleshooting
Integrating sites and services can sometimes be a little tricky, so we've put together some commonly-encountered issues and steps that can be taken to troubleshoot them.
Webhook Not Receiving Events
If your webhook isn't receiving events, the first place to check is the webhook's configuration. Is it setup to receive all events? If not, is it at least configured to receive your expected event?
If your webhook is configured to receive the event, but it isn't, the next place to check is the Recent Deliveries page for that webhook. Do you see any events attempting delivery? Are there any indicators of the issue under the expanded response details?
One of the last things to try is taking your webhook endpoint out of the equation, altogether. Create a temporary webhook endpoint on a service like Hookbin. Update the webhook configuration in Vanilla to use this new webhook endpoint URL. Do you see the expected events being delivered there?