Configure and verify webhooks

RIIW webhooks notify an external HTTPS endpoint about selected organization events. Each endpoint belongs to a service account or OAuth installation, inherits that principal’s organization boundary, and uses its own signing secret.

Prepare the receiver

Expose a public HTTPS URL that can accept POST requests and return a successful status quickly. RIIW rejects loopback, private, link-local, metadata, reserved, and otherwise unsafe destinations. Redirects are not followed, and DNS is revalidated to reduce rebinding risk.

The receiver should read the exact raw request bytes before JSON parsing, verify the timestamp and signature, record the event ID durably, and then acknowledge. Move slow processing to your own queue. Delivery is at least once and ordering is not guaranteed, so processing must be idempotent.

Create an endpoint

1. Create or identify a service account or OAuth installation with the required access.
2. Open Organization settings → API & Webhooks.
3. Open the Signing principal dropdown, select the owning principal, enter an endpoint name and HTTPS URL, and choose event types.
4. Select Verify and activate.
5. RIIW sends a signed endpoint.test request. The endpoint becomes active only after that test succeeds.
6. Copy the signing secret immediately and store it in a secrets manager.

Webhook payloads contain safe identifiers, event time, API version, actor metadata, resource version, and changed-field names. They do not include document or file contents, chat message bodies, member email addresses, storage paths, or provider credentials. Direct-message events are excluded.

Verify signatures

Construct the signed value from the X-RIIW-Timestamp header, a period, and the exact raw request body. Calculate hex HMAC-SHA256 with the endpoint secret and compare it in constant time with the v1 value in X-RIIW-Signature.

signed = X-RIIW-Timestamp + "." + rawBody
expected = hex(HMAC-SHA256(secret, signed))

Reject malformed signatures and timestamps outside your accepted clock-skew window. Do not log the secret, full signature inputs, or sensitive downstream data.

Retries, dead letters, and replay

Temporary failures are retried with backoff. Use the delivery list to inspect status and attempt count. A delivery that exhausts retry policy becomes dead-lettered. After fixing the receiver, select Replay for eligible delivered or dead-lettered records from the last seven days. Replay creates a new generation while preserving previous attempt history.

Deduplicate by eventId for business processing and retain deliveryId for delivery diagnostics. Return a success only after the event is durably accepted; returning success before persistence can lose work in your system.

Rotate or remove a secret

Rotation keeps the endpoint and creates a replacement secret. For 24 hours, RIIW sends the new signature and a previous-secret signature so consumers can deploy safely. Accept either valid signature during the grace period, then remove the old secret.

Removing an endpoint revokes its signing material and cancels its queued deliveries. Temporarily paused webhook delivery behaves differently: events and pending deliveries are preserved and resume without creating duplicates when service is restored.

For retry decisions and common problem codes, read Handle API errors, retries, and concurrency.