Skip to main content

Webhooks

A webhook subscription tells Connect to POST matching events to an endpoint you run. Manage subscriptions with the webhookSubscriptions resource in the Connect SDK or the Connect API reference.

Endpoint requirements

Connect checks the endpoint URL when you create or update a subscription, and again before every delivery. The URL must:
  • use https
  • not include a user name or password
  • resolve only to public addresses, not private, loopback, link-local, or cloud metadata ranges
  • not point at a Voyant host, such as voyant.travel, onvoyant.com, onvoyant.net, or voyanthub.com, or any of their subdomains
A delivery to a URL that no longer meets these rules is recorded as failed and is not sent. Connect does not follow redirects. Your endpoint must answer with a 2xx status. A 3xx response counts as a failed delivery, so point the subscription at the final URL.

Delivery headers

Every delivery carries these headers: Custom headers you configure on a subscription are sent too. They cannot set or replace the signature or timestamp headers above, and a subscription that tries is rejected.

Verify a delivery

Verify X-Webhook-Signature-V2. It binds the signature to the delivery time, so you can reject a delivery that is replayed later.
  1. Read the raw request body as bytes, before any JSON parsing.
  2. Read X-Webhook-Delivery-Timestamp. Reject the request if it is more than five minutes away from your current time.
  3. Compute the HMAC-SHA256 of {timestamp}.{raw body} with your subscription secret and hex-encode it.
  4. Compare sha256={your digest} with X-Webhook-Signature-V2 using a constant-time comparison.
X-Webhook-Signature signs the body without a timestamp, so it cannot tell a fresh delivery from a replayed one. It stays in place so current receivers keep working. Move your verification to X-Webhook-Signature-V2. The older header will be retired in a later release.