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 community events, such as user registrations and new comments.
✔️ TIP: If you're new to webhooks, we recommend that you read the following articles before getting started.
Webhook events
Higher Logic Vanilla (Vanilla) provides several webhook events that you can configure for your community. For example, you can set up:
- one webhook to receive notifications for all available events or
- several webhooks to receive notifications for different events.
This section describes the webhook events (presented alphabetically) that are currently available in your Vanilla community.
Article
A webhook event fires when an article is:
- Added
- Edited
- Deleted
- Restored
📝 NOTE: When an article is deleted or restored, it fires as an article_update event.
Answer
A webhook event fires when an answer to a question is:
Comment
A webhook event fires when a comment is:
Community Event
A webhook event fires 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
Discussion
A webhook event fires when a discussion is:
📝 NOTE: This applies to discussions, questions, polls, and ideas.
Escalation
A webhook event fires when:
- a post is escalated;
- an escalation is assigned to a user; and
- an escalation is updated.
📝 NOTE: An update could be, for example, a post being removed, a post being restored, an escalation's status being changed (e.g., from "open" to "in progress").
Group
A webhook event fires when a:
- Group is created
- Group is edited
- Group is deleted
- User joins a group
- User leaves a group
Notification
A webhook event fires when a:
- User receives a new notification
Reaction
A webhook event fires when a user:
- Reacts to a comment or discussion
- Removes their reaction from a comment or discussion
📝 NOTE: This includes ideation votes.
Report
A webhook event fires when a:
- post is reported
- report is updated
📝 NOTE: A report update could be, for example, when a community manager dismisses the report, or approves or rejects the publication of the post.
User
A webhook event fires when a:
- User is registered or is added
- User updates their profile information
- User is deleted
- User is banned/unbanned
- User earns a badge
- User's rank has changed
- User earns points
📝 NOTE: User bans fire as a user_update event.
Warnings & Notes
A webhook event fires when a:
- User is warned
- A note is added to a user's profile
Enable the Webhooks addon
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 that are configured for your community.
Add a webhook
- Click Add Webhook.
- 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.
- Active - this toggle determines whether events will be sent to a webhook. You can safely activate and deactivate a webhook without losing its configuration.
- Include user email - enable this setting if you want users' email addresses included in the user fragments of webhook deliveries. 📝 NOTE: User email addresses are always included for User webhook events.
- Include private profile fields - enable this setting if you want private profile fields included in the user fragments of webhook deliveries.
- Include internal profile fields - enable this setting if you want internal profile fields 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
When you have at least one webhook configured, it displays in the list.
To edit a webhook:
- Click the webhook's edit (pencil) icon.
- Make any desired updates.
- Click Save to apply them.
Delete a webhook
🛑 WARNING: Before you delete a webhook, consider that its configuration is deleted and all associated data is irrecoverably lost.
✔️ TIP: Instead of deleting a webhook, you might want to deactivate it (using the Active toggle that is described above).
To delete a webhook:
- Click the webhook's delete (trashcan) icon.
- Confirm the deletion.
The webhook is deleted.
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 are arranged in a table with 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 are highlighted in red.
A clickable chevron icon is to the left of each Delivery ID. Click it to view additional details about the delivery; 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 includes 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 be 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?