Webhook Verification

To ensure that you are the owner of the endpoint you configure, we perform a verification step when saving a new endpoint. You need to pass the verification to have the webhook activated. When validating, a GET request will be performed on your callback URL with a type query parameter with value subscribe and a challenge parameter with a validation string. Example:

Request: GET https://hooker:z3kruT@example.com/cs-webhook?type=subscribe&challenge=hmsmYGrwPFrWYbN

To have the callback URL validated using this request, make sure the webhook returns the challenge parameter value as the response body, and make sure that the response body is in plain text (no markup, whitespaces, etc.).

Prior to verification, the Service status will be set to unverified Verification is performed when the params.url changes, or when the service status is set to active for example:

Request: PATCH /v2/services/5a8602c0d1c2b71bc31b38fe

{
    "status": "active"
}

This will return a 403 error if the callback URL could not be verified, and update the status otherwise.

Webhook Payload Validation

There's nothing to stop someone who knows our webhook URL from crafting false event data and sending it to the URL. Luckily, each payload comes with a signed HMAC signature so that you can verify the origin of the webhook request.

When a webhook is created, a shared secret will be generated for it (if not provided). The secret can be used to determine the veracity of a request to your webhook route. This params.secret is used as a key to sign the payload data: the HMAC key is your params.secret security token, the HMAC digest is SHA1, and the data is the raw payload JSON that is sent. The hash signature is passed along hex-encoded with each request via the X-Hub-Signature HTTP header. The hash signature starts with sha1=. We will show you a code example later on that does this.

To validate the request payload, you need to encode the payload string with HMAC, using the secret as the key and SHA1 as the algorithm. The result should be the same as the signature.