Verify HeyStream webhook signatures

HeyStream signs every outbound webhook delivery with the signing secret shown in your webhook settings. Verifying the signature helps your endpoint confirm that the event came from HeyStream and that the request body was not changed in transit.

You can receive webhook events without verifying signatures, but we recommend verification for production endpoints.

What HeyStream sends

Each webhook request includes these headers:

• X-HeyStream-Signature: the HMAC-SHA256 signature, prefixed with sha256=

• X-HeyStream-Timestamp: the Unix timestamp, in seconds, used when creating the signature

• X-HeyStream-Delivery: the unique delivery ID for the event

• X-HeyStream-Event: the event type, such as contact.registered

How to verify a signature

Use the signing secret from your webhook settings and the raw request body exactly as it was received.

1. Read the X-HeyStream-Timestamp header.

2. Read the X-HeyStream-Signature header and remove the sha256= prefix.

3. Build the signed payload as timestamp, then a period, then the raw request body.

4. Create an HMAC-SHA256 digest of that signed payload using your webhook signing secret.

5. Compare your digest with the signature header using a constant-time comparison.

6. Reject requests with old timestamps. Five minutes is a good default tolerance.

The signed payload format is:

timestamp.raw_request_body

Important implementation notes

• Verify the signature before processing the event.

• Use the raw body, not the parsed JSON object. Parsing and re-stringifying JSON can change whitespace or key ordering, which will make the signature check fail.

• Keep the signing secret private. Do not expose it in client-side code or logs.

• Regenerate the signing secret if you think it has been shared somewhere unsafe.

Regenerating a signing secret

You can regenerate the signing secret from the webhook settings drawer in HeyStream.

After you save a regenerated secret, HeyStream signs future webhook deliveries with the new secret. Update your receiving endpoint before or immediately after saving the new secret so it can continue verifying deliveries.