Receive webhooks

Organization admins can create HTTPS webhook endpoints from Webhooks. The signing secret is shown once. Store it before leaving the result page; later reads return endpoint metadata only.

Delivery contract

Queued deliveries are retried and may arrive more than once. Receivers must:

1. Read the raw request body before JSON re-serialization.
2. Reject a timestamp older than 300 seconds.
3. Verify at least one v1 signature with a constant-time comparison.
4. Deduplicate on X-Gateway-Delivery-Id.
5. Return a 2xx status only after the event is durably accepted.

The signing input is:

"v1:" || timestamp || ":" || delivery_id || ":" || raw_body_bytes

The X-Gateway-Signature header contains v1=<lowercase hex HMAC-SHA256>. During secret rotation, the header can contain two comma-separated v1 values so receivers can roll without downtime.

Event types

The implemented approval fan-out emits:

• approval.requested
• approval.resolved
• approval.executed
• approval.failed

The endpoint test sends webhook.test synchronously. It is not queued and is not filtered by the endpoint’s subscribed event types.

Retries and replay

Alcarta leases each delivery and retries failures according to its outbox policy. Exhausted items become dead and remain visible in Deliveries. Replay creates a new delivery; it never reopens the terminal row.

Webhook URLs are checked by the same outbound network guard used for provider endpoints, both when configured and immediately before delivery.