Skip to main content
Already sends signed HTTP POST requests to the callback registered for your partner. Register it in Already admin → Connections or through POST /partner/v1/webhooks; use one endpoint unless you intentionally want multiple copies. Hosted callbacks must use public HTTPS. Localhost is accepted only by a local development API.
The creation response shows a signingSecret once. Store it in your server-side secret manager. You may use "*" to receive every event. Trigger an integration.test event with POST /partner/v1/webhooks/test or the admin Connections page.

Verify each delivery

Already sends X-Already-Event-Id, X-Already-Timestamp (Unix seconds), and X-Already-Signature (v1= followed by a lowercase hexadecimal HMAC-SHA256 digest). Compute the HMAC with your signing secret over:
Compare signatures in constant time, reject timestamps outside a five-minute window, and deduplicate by event ID. Verify the raw bytes before parsing or reserializing JSON. Return a 2xx response after durably accepting the event. Do not treat the request’s source IP as a substitute for signature verification.

Retries and recovery

Delivery is at least once: your handler must be idempotent. Failed HTTP responses and network errors retry with exponential backoff, up to eight attempts. A callback can be delayed, and event order should not be assumed across independent deliveries. Inspect delivery failures in Connections and recover with GET /partner/v1/events?after=<last-processed-id>&limit=50. Save nextCursor only after processing that page. The event reference lists emitted event types. The troubleshooting guide covers common delivery failures.