Introduction

Before any events are sent to a webhook, the platform verifies the organization's ownership of the webhook endpoint by performing the verification process described below. All newly created webhooks are subject to endpoint verification.

Verifying the Webhook Endpoint

The organization's ownership of a webhook's endpoint URL must be verified before any events are sent to it. This process uses the webhook's secret coupled with the well-known HMACSHA256 algorithm to generate a response to a challenge code.

The Verification Process

1. The platform generates a string that serves as the challengeCode.
2. The platform issues an HTTP GET request to the webhook endpoint, including the challengeCode as a querystring parameter:

GET https://example.com/webhook?challengeCode=b0d7d62e-2ca5-4928-a8ab-56850cd54126

3. Your service computes the challengeResponse — the HMACSHA256 signature for the challengeCode, using your webhook's secret as the secret key. Return both the challengeCode and challengeResponse in a JSON payload with a 200 OK status within 3 seconds:

{
  "challengeCode": "b0d7d62e-2ca5-4928-a8ab-56850cd54126",
  "challengeResponse": "A71r27obVGYehYvO2ggeSi9wUo9m/bI1WOUwJfrD+Do="
}

4. Upon receiving the verification response, the platform computes the expected challenge response and compares it with the challengeResponse returned by your service.
5. If the challengeResponse is successfully verified, the webhook's verification status switches to "Verified" and subscribed events start flowing to your webhook.

📘

Webhook endpoint verification occurs when a webhook is created or updated. Webhooks that have been previously verified are re-verified roughly every two hours.

Reverification

Verified webhook endpoints are reverified roughly every two hours. If a webhook fails reverification three times in a row, three things occur:

1. Its verification status changes from "Verified" to "Unverified."
2. Events stop flowing to the webhook.
3. Users in the organization with either the OrgOwner or Developer role receive an e-mail indicating that the webhook has become unverified.

After resolving the issue that caused the webhook to become unverified, a developer can manually trigger another verification from the Admin › Developer › Webhooks screen.

📘

Testing Webhooks

You can use a URL from https://webhook.site/ as your endpoint to verify that your webhook is sending events and inspect their payloads prior to setting up endpoint verification. This test domain is whitelisted and not subject to endpoint verification.

This should only be used for short periods while testing with non-production data.

Example Implementation

The following is an example C# implementation of the challenge response computation:

using System;
using System.Security.Cryptography;
using System.Text;


public static string ComputeChallengeResponse(string challengeCode, string clientSecret)
{
    var hmacKeyBytes = Encoding.UTF8.GetBytes(clientSecret);

    using var hmacSha256 = new HMACSHA256(hmacKeyBytes);
    var stringToSignBytes = Encoding.UTF8.GetBytes(challengeCode);
    var signatureBytes = hmacSha256.ComputeHash(stringToSignBytes);
    var signatureHash = Convert.ToBase64String(signatureBytes);
    return signatureHash;
}