Customer webhooks

Customer webhooks deliver canonical operation outcomes to an HTTPS endpoint you control. Create a subscription in Settings → Webhooks or with POST /v1/webhooks. The signing secret is shown once.

Delivery contract

Every request contains a JSON payload with schema_version, event_id, event_type, occurred_at, and safe operation identifiers in data.

Verify these headers before accepting the body:

• Ankk-Webhook-Id: stable delivery ID; use it to deduplicate retries.
• Ankk-Webhook-Event: event type.
• Ankk-Webhook-Timestamp: ISO timestamp used by the signature.
• Ankk-Webhook-Signature: v1= followed by the hex HMAC-SHA256 signature.

Compute the HMAC over <timestamp>.<raw request body> with the signing secret and compare it in constant time. Return a 2xx response only after your system has durably accepted the event.

Retries and safety

Delivery is at least once. Ankk Threads retries failures with backoff, leases work so another worker can recover it, and moves a delivery to the dead-letter state after eight attempts. Receivers must deduplicate by delivery ID.

Targets must use public HTTPS addresses. Loopback, private, link-local, and credential-bearing URLs are rejected. Payloads exclude credentials, email addresses, raw provider responses, and free-form provider error messages.

Use GET /v1/webhook-deliveries or ankk-threads webhooks deliveries to inspect canonical delivery outcomes.