Adrata Developers

Webhooks

Signed outbound webhook infrastructure with fanout, filters, retries, DLQ, replay, and delivery-status-aware event cataloging.

Create subscription

curl https://api.adrata.com/api/v1/webhooks \
  -H "Authorization: Bearer $ADRATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/adrata/webhook","events":["webhook.test","opportunity.stage_changed","opportunity.closed_won"],"active":true}'

Verify

import { verifyWebhook } from '@adrata/sdk';

const ok = verifyWebhook(rawBody, req.headers['x-adrata-signature'], process.env.ADRATA_WEBHOOK_SECRET!);

Rotate signing secret

curl -X POST https://api.adrata.com/api/v1/webhooks/{id}/secret/rotate \
  -H "Authorization: Bearer $ADRATA_API_KEY"

Delivery contract

Webhook deliveries require HTTPS, use a 10 second request timeout, and include stable delivery/event IDs plus Stripe-format `X-Adrata-Signature: t=...,v1=...` signatures with `X-Adrata-Signature-Key-Id` metadata.

Adrata retries HTTP 429, HTTP 5xx, and transport failures for up to 7 total attempts with fixed backoff: 1 second, 5 seconds, 30 seconds, 5 minutes, 30 minutes, 2 hours, then 12 hours. Other HTTP 4xx responses are terminal failures.

Operations

Use `GET /api/v1/webhooks/events` for the event catalog and subscribe only to entries with `deliveryStatus: "available"`. Use `POST /api/v1/webhooks/{id}/test` for endpoint validation, `GET /api/v1/webhooks/{id}/deliveries` for delivery history, `POST /api/v1/webhooks/{id}/deliveries/{delivery_id}/replay` for controlled replay, and `POST /api/v1/webhooks/{id}/secret/rotate` to issue a new encrypted signing secret returned once.

Secret rotation is immediate for future deliveries and includes a 24 hour old/new overlap window: Adrata sends both current and previous `v1` HMAC values in `X-Adrata-Signature` until `previousSecretExpiresAt`, with `signingKeyId` and `previousSigningKeyId` for receiver audit trails.

MCP exposes the same workflow through `list_webhook_events`, `create_webhook`, `test_webhook`, `list_webhook_deliveries`, and `replay_webhook_delivery`.