Webhooks - Vanilla Success
<main> <article class="userContent"> <p>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. </p><p>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:</p><ul><li><a href="https://zapier.com/blog/what-are-webhooks/" rel="nofollow noreferrer ugc">What Are Webhooks?</a> by Zapier</li><li><a href="https://sendgrid.com/blog/whats-webhook/" rel="nofollow noreferrer ugc">What's a Webhook?</a> by SendGrid</li></ul><h2 data-id="webhook-events">Webhook Events</h2><p>We currently have several webhook events available 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 the Webhook Events currently supported:</p><p><strong>Discussions: </strong>Events are fired when -</p><ul><li>Discussions are added</li><li>Discussions are edited</li><li>Discussions are deleted</li><li>Discussions are tagged</li></ul><p><em>This applies to all discussion types (questions, polls, and ideas)</em></p><p><strong>Comments: </strong>Events are fired when -</p><ul><li>Comments are added</li><li>Comments are edited</li><li>Comments are deleted</li></ul><p><strong>Articles: </strong>Events are fired when -</p><ul><li>Articles are added</li><li>Articles are edited</li><li>Articles are deleted</li><li>Articles are restored</li></ul><p><em>N.B. When an article is deleted or restored is will be fired as an article_update event.</em></p><p><strong>Groups: </strong>Events are fired when - </p><ul><li>A Group is created</li><li>A Group is edited</li><li>A Group is deleted</li><li>A user joins a group</li><li>A user leaves a group</li></ul><p><strong>Answers: </strong>Events are fired when:</p><ul><li>An answer to a question is rejected</li><li>An answer to a question is accepted</li></ul><p><strong>Users: </strong>Events are fired when:</p><ul><li>A user registered or is added</li><li>A users profile information is updated</li><li>A user is deleted</li><li>A user is banned or unbanned</li><li>A user earns a badge</li><li>A user's rank has changed</li><li>A user earns points</li></ul><p><em>N.B. User bans will be fired as a user_update event.</em></p><p><strong>Reaction: </strong>Events are fired when:</p><ul><li>A user reacts to a comment or discussion</li><li>A user removes their reaction from a comment or discussions</li></ul><p><em>N.B. This also includes Ideation Votes</em></p><p><strong>Events: </strong>Events are fired when:</p><ul><li>A Community or Group Event is added </li><li>A Community or Group Event is updated</li><li>A Community or Group Event is deleted</li><li>A user RSVPs or updates their RSVP to a Community or Group Event</li></ul><p><strong>User Note: </strong>Events are fired by our Warnings & Notes add-on when:</p><ul><li>A user is warned</li><li>A note is added to a user's profile</li></ul><p><strong>Notification: </strong>Events are fired when a user receives a new notification.</p><h2 data-id="setup">Setup</h2><p>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.</p><h3 data-id="adding-a-webhook">Adding a Webhook</h3><p>Clicking "Add Webhook" from the list will display a simple form with five configurable elements:</p><ol><li><strong>Name</strong> 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.</li><li><strong>Delivery Url</strong> 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.</li><li><strong>Secret</strong> 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.</li><li>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.</li><li>The <strong>Active</strong> toggle determines whether or not events will be sent to a webhook. You can safely activate and deactivate a webhook without losing its configuration.</li><li>You can enable the <strong>Include user email</strong> option if you'd like user emails to be included in the user fragments of webhook deliveries. N.B. emails are always included for "User" webhook events. </li></ol><p>Once you've configured your webhook, click "Save" to create the entry and you're all set.</p><h3 data-id="editing-a-webhook">Editing a Webhook</h3><p>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.</p><h3 data-id="deleting-a-webhook">Deleting a Webhook</h3><p>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.</p><p>Disabling a webhook may be a more suitable alternative than deleting it.</p><h2 data-id="recent-deliveries">Recent Deliveries</h2><p>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:</p><ol><li><strong>Delivery ID</strong> is a globally-unique identifier for the delivery attempt. These are generated at the time of the request.</li><li>The <strong>Date</strong> when the delivery was initiated.</li><li><strong>Duration</strong> indicates the time, in seconds, between when the request was initiated and when a response was received to complete it.</li><li>A <strong>Status</strong> code of the HTTP response, if available. Error codes will be highlighted in red.</li></ol><p>A clickable chevron icon will also be present at the start of each row, alongside <strong>Delivery ID</strong>. 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.</p><p>Currently, only the most-recent fifty deliveries are displayed. They are listed by <strong>Date</strong> in descending order.</p><h2 data-id="signing">Signing</h2><p>One of the most important parts of securing your webhooks integration is verifying signatures. Every webhook delivery sent by Vanilla will include a <code class="code codeInline" spellcheck="false" tabindex="0">X-Vanilla-Signature</code> 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 <strong>Secret</strong>. 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 <code class="code codeInline" spellcheck="false" tabindex="0">X-Vanilla-Signature</code> header. If the signatures do not match, the event should not be trusted.</p><h2 data-id="troubleshooting">Troubleshooting</h2><p>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.</p><h3 data-id="webhook-not-receiving-events">Webhook Not Receiving Events</h3><p>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?</p><p>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?</p><p>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 <a href="https://hookbin.com" rel="nofollow noreferrer ugc">Hookbin</a>. Update the webhook configuration in Vanilla to use this new webhook endpoint URL. Do you see the expected events being delivered there?</p> </article> </main>