How to set up signed webhooks

Sparkles webhooks are the primary event delivery mechanism. Each request contains one event and uses an HMAC-SHA256 signature over the exact request bytes.

Prerequisites

An active Sparkles API access grant.
A public HTTPS endpoint on port 443.
A handler that can read the unmodified request body.

Webhook URLs cannot contain credentials, a query string, or a fragment. Their hostname must resolve only to public IP addresses and cannot point back to Sparkles.

Step 1: Register an endpoint

Open the API access page, enter your endpoint URL, and copy the whsec_ signing secret. Sparkles shows the secret only when it is created or rotated. Keep the endpoint pending until your server implements signature and challenge verification.

Step 2: Verify every request

Read these headers before parsing the JSON body:

Header	Meaning
`Webhook-Id`	Stable UUID equal to the event body’s `id`. Use it as the idempotency key.
`Webhook-Timestamp`	Unix seconds included in the signature input. Reject values outside five minutes.
`Webhook-Signature`	One or more space-separated `v1,BASE64_HMAC` signatures.
`Webhook-Attempt`	One-based delivery attempt number. Omitted during endpoint verification.

The signed value is:

Webhook-Id + "." + Webhook-Timestamp + "." + rawRequestBody

This TypeScript verifies the timestamp and accepts any valid signature in constant time:

import { createHmac, timingSafeEqual } from 'node:crypto';

const SIGNING_SECRET_PREFIX = 'whsec_';
const TIMESTAMP_TOLERANCE_SECONDS = 5 * 60;

function signingKey(secret: string) {
	if (!secret.startsWith(SIGNING_SECRET_PREFIX)) throw new Error('Invalid signing secret');
	const key = Buffer.from(secret.slice(SIGNING_SECRET_PREFIX.length), 'base64');
	if (key.byteLength !== 32) throw new Error('Invalid signing secret');
	return key;
}

export function verifySparklesWebhook(input: {
	secret: string;
	webhookId: string;
	timestamp: string;
	signature: string;
	rawBody: string;
	nowSeconds?: number;
}) {
	const timestamp = Number(input.timestamp);
	const nowSeconds = input.nowSeconds ?? Math.floor(Date.now() / 1000);
	if (
		!Number.isInteger(timestamp) ||
		Math.abs(nowSeconds - timestamp) > TIMESTAMP_TOLERANCE_SECONDS
	) {
		throw new Error('Stale webhook');
	}

	const signed = `${input.webhookId}.${timestamp}.${input.rawBody}`;
	const expected = createHmac('sha256', signingKey(input.secret)).update(signed).digest();
	const valid = input.signature.split(/\s+/).some((value) => {
		if (!value.startsWith('v1,')) return false;
		const received = Buffer.from(value.slice(3), 'base64');
		return received.byteLength === expected.byteLength && timingSafeEqual(received, expected);
	});
	if (!valid) throw new Error('Invalid webhook signature');
}

During signing-secret rotation, Sparkles sends both the old and new signatures for 24 hours. Accept either valid v1 value, then remove the old secret after the overlap ends.

Step 3: Answer endpoint verification

Selecting Verify endpoint sends a signed endpoint.verification request:

{
	"id": "f78c1f7e-dc41-4302-880b-97283679c30b",
	"type": "endpoint.verification",
	"data": {
		"challenge": "jQvWIfGqvJX_q4XJ-Qs5vC31NBBvAJXLw5NR5oBTZ4U"
	},
	"createdAt": "2026-08-03T10:10:00.000Z"
}

Verify its normal request signature, then add this response function to the same module:

export function verificationResponse(secret: string, challenge: string) {
	const response = createHmac('sha256', signingKey(secret))
		.update(`sparkles.webhook.verify.${challenge}`)
		.digest('base64');
	return JSON.stringify({ response });
}

Verification requests do not contain sequence or Webhook-Attempt.

Step 4: Acknowledge durable acceptance

Return any 2xx response only after saving the event durably. Delivery is at least once, so deduplicate on the body UUID before applying side effects. Sparkles retries transient failures after approximately 1 minute, 5 minutes, 30 minutes, 2 hours, 8 hours, 1 day, 2 days, and 3 days. An HTTP 429 response may override the next delay through Retry-After, capped at one day. Return HTTP 410 to disable the endpoint and stop delivery.

Verification

The API access page marks the endpoint active after it receives a valid challenge response. A delivered event should have a matching body id and Webhook-Id, a current timestamp, and a valid signature.

Troubleshooting

Signature mismatch: verify against the raw bytes before JSON parsing or reserialization.
Verification timeout: respond within 15 seconds with no more than 4 KiB of JSON.
Endpoint rejected: use public HTTPS on port 443 without a query string or fragment.
Duplicate event: acknowledge it without applying its side effects again.

Get started

Integration guides

API reference

How to set up signed webhooks

Prerequisites

Step 1: Register an endpoint

Step 2: Verify every request

Step 3: Answer endpoint verification

Step 4: Acknowledge durable acceptance

Verification

Troubleshooting

​Prerequisites

​Step 1: Register an endpoint

​Step 2: Verify every request

​Step 3: Answer endpoint verification

​Step 4: Acknowledge durable acceptance

​Verification

​Troubleshooting

Prerequisites

Step 1: Register an endpoint

Step 2: Verify every request

Step 3: Answer endpoint verification

Step 4: Acknowledge durable acceptance

Verification

Troubleshooting