Webhooks - HL Vanilla Community
<main> <article class="userContent"> <p><strong>Webhooks </strong>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 <strong>Webhooks </strong>addon allows you to receive automated notifications about key events, like user registrations or new comments. </p><p><strong>✔️ TIP</strong>: If you're new to webhooks, we recommend reading the following articles 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><strong>Higher Logic Vanilla (Vanilla)</strong> provides several webhook <strong>events </strong> 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><h3 data-id="discussions">Discussions</h3><p>Events are fired when <strong>discussions </strong>are:</p><ul><li>Added</li><li>Edited</li><li>Deleted</li><li>Tagged</li></ul><p><strong>📝 NOTE</strong>: This applies to <strong>all</strong> discussion types (discussions, questions, polls, and ideas).</p><h3 data-id="comments">Comments</h3><p>Events are fired when <strong>comments </strong>are:</p><ul><li>Added</li><li>Edited</li><li>Deleted</li></ul><h3 data-id="articles">Articles</h3><p>Events are fired when <strong>articles </strong>are:</p><ul><li>Added</li><li>Edited</li><li>Deleted</li><li>Restored</li></ul><p><strong>📝 NOTE</strong>: When an article is deleted or restored, it will be fired as an <code class="code codeInline" spellcheck="false" tabindex="0">article_update</code> event.</p><h3 data-id="groups"><strong>Groups</strong></h3><p>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><h3 data-id="answers">Answers</h3><p>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><h3 data-id="users">Users</h3><p>Events are fired when:</p><ul><li>A user registered or is added</li><li>A user's profile information is updated</li><li>A user is deleted</li><li>A user is banned/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><strong>📝 NOTE</strong>: User bans will be fired as a <code class="code codeInline" spellcheck="false" tabindex="0">user_update</code> event.</p><h3 data-id="reactions">Reactions</h3><p>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 discussion</li></ul><p><strong>📝 NOTE</strong>: This also includes ideation votes.</p><h3 data-id="events">Events</h3><p>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><h3 data-id="warnings-notes">Warnings & Notes</h3><p>Events are fired by our Warnings & Notes addon when:</p><ul><li>A user is warned</li><li>A note is added to a user's profile</li></ul><h3 data-id="notifications">Notifications</h3><p>Events are fired when:</p><ul><li>A user receives a new notification</li></ul><h2 data-id="enable-the-webhooks-addon">Enable the Webhooks addon</h2><p><strong>📝 NOTE</strong>: This addon must be enabled by Vanilla staff. Contact Vanilla Support to have it enabled.</p><h2 data-id="view-your-webhooks">View your webhooks</h2><p>Once the Webhooks addon has been enabled, you can manage your webhooks in the <strong>Dashboard</strong>, on the <strong>Settings > API Integrations</strong> <strong>> Webhooks </strong>page. This page lists all of the webhooks configured for your community.</p><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/MIQ6L2D3U5OT/access-webhooks-page.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/MIQ6L2D3U5OT/access-webhooks-page.png" alt="access_webhooks_page.png" height="420" width="921" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <h2 data-id="add-a-webhook">Add a webhook</h2><p>1. Click <strong>Add Webhook</strong>.</p><div class="embedExternal embedImage display-medium float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/TDT2T133WHN8/add-webhook-button.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/TDT2T133WHN8/add-webhook-button.png" alt="add_webhook_button.png" height="397" width="759" loading="lazy" data-display-size="medium" data-float="none"></img></a> </div> </div> <p>2. In the resulting dialog, configure the five options:</p><ul><li><strong>Name</strong> 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.</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's important that 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's important that 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 <strong>select individual events</strong> and ensure <strong>User </strong>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>Enable the <strong>Include user email</strong> option if you'd like user emails to be included in the user fragments of webhook deliveries. Note that emails are <em>always </em>included for User webhook events. </li></ul><p>3. Once you've configured your webhook, click <strong>Save </strong>to create the entry.</p><h2 data-id="edit-a-webhook">Edit a webhook</h2><p>Once you have at least one webhook configured, you'll see it displayed in the list. To edit any of your existing webhooks:</p><ol><li>Click its associated <strong>edit (pencil) icon</strong>. </li><li>Make any desired updates.</li><li>Click <strong>Save </strong>to apply them.</li></ol><h2 data-id="delete-a-webhook">Delete a webhook</h2><p>To delete any of your existing webhooks:</p><ol><li>Clicks its associated <strong>delete (trashcan) icon</strong>. </li><li>Confirm the deletion. </li></ol><p>If the action is confirmed, the webhook configuration will be deleted, and all associated data will be irrecoverably lost.</p><p><strong>✔️ TIP</strong>: In some instances, disabling a webhook may be a more suitable alternative than deleting it.</p><h2 data-id="view-a-webhook's-recent-deliveries">View a webhook's recent deliveries</h2><p>Each row in the list of webhooks contains the <strong>recent deliveries</strong> <strong>(clock) icon</strong>. Click this to view 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><strong>📝 NOTE</strong>: Currently, only the most-recent <strong>fifty </strong>deliveries are displayed. They are listed by <strong>Date</strong> in descending order.</p><h2 data-id="webhook-signatures">Webhook signatures</h2><p>One of the most important parts of securing your webhooks integration is verifying <strong>signatures</strong>. 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: </p><ul><li>the algorithm used to generate the signature </li><li>and the signature itself. </li></ul><p>Vanilla currently uses the <strong>SHA-1</strong> 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><ul><li>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?</li><li>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?</li><li>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?</li></ul> </article> </main>