Webhooks

Webhooks are for event-driven integrations that should not poll the API continuously.

Supported event types:

• signal.created — A new scored signal was generated
• export.completed — An async export job finished successfully
• export.failed — An async export job failed
• saved_query.completed — A saved query execution completed
• intelligence.refreshed — Match intelligence was refreshed

Verify every delivery

Webhook deliveries should be verified with the documented HMAC signature header before processing.

Subscription lifecycle

1. Create a webhook subscription with the target URL and event types.
2. Store the returned secret once if the endpoint exposes it at creation time.
3. Verify signatures on every request.
4. Handle duplicate deliveries idempotently.
5. Inspect delivery history when debugging.

Handler skeleton

export async function handleFutPicksWebhook(req: Request) {
  const signature = req.headers.get('X-Webhook-Signature');  // sha256={hex}
  const deliveryId = req.headers.get('X-Webhook-Delivery-Id');
  const eventType = req.headers.get('X-Webhook-Event-Type');
  const timestamp = req.headers.get('X-Webhook-Timestamp');
  const body = await req.text();

  verifyHmacSha256(body, signature, secret);

  const event = JSON.parse(body);
  await processEventIdempotently(deliveryId, eventType, event);
}

Webhook deliveries include these headers:

Header	Description
X-Webhook-Signature	HMAC-SHA256 signature with sha256= prefix
X-Webhook-Delivery-Id	Unique delivery identifier
X-Webhook-Event-Type	Event type (e.g. signal.created)
X-Webhook-Timestamp	ISO 8601 delivery timestamp
X-Webhook-Api-Version	API version string