Webhooks
A webhook subscription tells Connect toPOST 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, orvoyanthub.com, or any of their subdomains
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
VerifyX-Webhook-Signature-V2. It binds the signature to the delivery time, so you can reject a delivery that is replayed later.
- Read the raw request body as bytes, before any JSON parsing.
- Read
X-Webhook-Delivery-Timestamp. Reject the request if it is more than five minutes away from your current time. - Compute the HMAC-SHA256 of
{timestamp}.{raw body}with your subscription secret and hex-encode it. - Compare
sha256={your digest}withX-Webhook-Signature-V2using 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.