Webhooks are a great way to improve integrations between sites and services. They provide an automated way to keep separate systems up to date about site activity. The Webhooks addon allows you to receive automated notifications about key events, such as user registrations and new comments.
✔️ TIP: If you're new to webhooks, we recommend reading the following articles before getting started:
Webhook events
Higher Logic Vanilla (Vanilla) provides several webhook events for configuration. You can set up a webhook to receive notifications for all available events, or configure different webhooks for different events. Below are the webhook events currently supported:
Discussions
Events are fired when discussions are:
📝 NOTE: This applies to all discussion types (discussions, questions, polls, and ideas).
Comments
Events are fired when comments are:
Articles
Events are fired when articles are:
- Added
- Edited
- Deleted
- Restored
📝 NOTE: When an article is deleted or restored, it will be fired as an article_update event.
Groups
Events are fired when a:
- Group is created
- Group is edited
- Group is deleted
- User joins a group
- User leaves a group
Answers
Events are fired when an answer to a question is:
Users
Events are fired when a:
- User is registered or is added
- User's profile information is updated
- User is deleted
- User is banned/unbanned
- User earns a badge
- User's rank has changed
- User earns points
📝 NOTE: User bans will be fired as a user_update event.
Reactions
Events are fired when a user:
- Reacts to a comment or discussion
- Removes their reaction from a comment or discussion
📝 NOTE: This also includes ideation votes.
Events
Events are fired when a:
- Community or Group Event is added
- Community or Group Event is updated
- Community or Group Event is deleted
- User RSVPs or updates their RSVP to a Community or Group Event
Warnings & Notes
Events are fired by our Warnings & Notes addon when a:
- User is warned
- Note is added to a user's profile
Notifications
Events are fired when a:
- User receives a new notification
Enable the Webhooks addon
📝 NOTE: This addon must be enabled by Vanilla staff. Contact Vanilla Support to have it enabled.
View your webhooks
With the Webhooks addon enabled, you can manage your webhooks in the Dashboard, on the Settings > API Integrations > Webhooks page. This page lists all of the webhooks configured for your community.
Add a webhook
1. Click Add Webhook.
2. On the Add Webhook page, configure the options:
- Name is a user-friendly name for this webhook. It's only used in the UI, and does not have any direct impact on functionality. Just choose something that makes sense to you, especially if you have (or will 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's important that 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 with Vanilla. That is why it's important that this value be cryptographically-secure and never disclosed to untrusted parties.
- You can configure whether your webhook should receive all available event types in Vanilla or only a subset. For example, if you're interested in registrations specifically, toggle on select individual events and ensure User is the only box checked.
- The Active toggle determines whether events will be sent to a webhook. You can safely activate and deactivate a webhook without losing its configuration.
- Enable the Include user email setting if you'd like user email addresses to be included in the user fragments of webhook deliveries. Note that email addresses are always included for User webhook events.
- Enable the Include private profile fields setting if you'd like private profile fields to be included in the user fragments of webhook deliveries.
- Enable the Include internal profile fields setting if you'd like internal profile fields to be included in the user fragments of webhook deliveries.
✔️ TIP: Private and Internal profile fields are set via the Visibility setting when you add or edit Custom Profile Fields on the Settings > Membership > User Profile page of the Dashboard. To learn about these settings, see the Create a custom profile field section.
3. Once you've configured your webhook, click Save to create the entry.
Edit a webhook
Once you have at least one webhook configured, you'll see it displayed in the list. To edit a webhook:
- Click its associated edit (pencil) icon.
- Make any desired updates.
- Click Save to apply them.
Delete a webhook
To delete a webhook:
- Clicks its associated delete (trashcan) icon.
- Confirm the deletion.
If the action is confirmed, the webhook configuration will be deleted and all associated data will be irrecoverably lost.
✔️ TIP: In some instances, disabling a webhook may be a more suitable alternative than deleting it.
View a webhook's recent deliveries
Each row in the list of webhooks contains the recent deliveries (clock) icon. Click this to view 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.
📝 NOTE: Currently, only the most-recent fifty deliveries are displayed. They are listed by Date in descending order.
Webhook signatures
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?
