Set up webhooks

Learn how to use webhooks to notify your application when an event happens.

Register a webhook

  1. Go to the Apps page in the Envoy dashboard
  1. Click Configure on the Webhooks card
  2. Under Events select the webhook event type you want to subscribe to
  3. Enter the full URL path of the endpoint you want the webhook callback to be posted to in the Webhook URLs field
  1. Click Complete Setup


You can configure HTTP Basic authentication for your webhook endpoint by providing a username and password as username:password. This will be included in the header of the request when it's sent to your server.

Verify a webhook

To verify that the webhook message originated from Envoy, a signature header X-Envoy-Signature is included in each webhook message. This signature is a Base64-encoded string that represents a SHA-256 HMAC of the request body, using your app's client secret as the key.

You can validate the signature by building your own signature of the request body signed with your client secret and comparing the two signatures. If the signature does not match you should reject the request.


All of the official Envoy SDKs verify signatures automatically.

OpenSSL::HMAC.hexdigest ( ('sha256'), api_key, '%s%s' % [timestamp, token])

Retrying webhooks

Envoy has retry logic to resend a webhook if a successful response (2xx) is not returned by your server. Webhooks are retried 5 times over the span of 10 minutes.