Skip to main content
Webhooks are the signed delivery mechanism Shodai uses to send compact events to your backend. A webhook subscription belongs to an API principal, points to one HTTPS receiver URL, and can receive one or more subscribed event families. Use this page for subscription setup, verification, retries, testing, and shared delivery behavior. Use Agreement activity webhooks for agreement lifecycle reconciliation, and Notification webhooks for notification-rule deliveries.

​
Webhook taxonomy

ConceptEvent typeUse it for
WebhooksN/AShared subscription, signing, delivery, retry, test, and filtering infrastructure.
Agreement activity webhooksagreement.transitionedMirroring or reconciling agreement lifecycle changes.
Notification webhooksagreement.notification.triggeredReceiving rule-fired notification content after Shodai evaluates notification templates.
Test deliverieswebhook.testTesting a receiver with a real signed POST. This is a delivery payload type, not a subscribable eventTypes value.
agreement.transitioned and agreement.notification.triggered are the only subscribable event types. A single subscription can receive either or both.

​
How webhooks are managed

You can manage webhook subscriptions in the Developer Portal or through the Agreements API and TypeScript SDK. Both paths manage subscriptions for the same API principal model. The API-key path uses /v0/webhooks. The Developer Portal resolves your signed-in account to the self-serve API principal and manages that principal’s subscriptions. A webhook belongs to the principal. If a webhook is created with an API key, createdByApiKeyId is audit context, not the ownership boundary. Webhook management requires webhooks.read and webhooks.write access for the API principal. For key setup and 401 or 403 troubleshooting, see Authentication.

​
Before you start

You need:
  • a Shodai API key or Developer Portal access
  • a public HTTPS endpoint that can receive POST requests
  • server-side access to the exact raw request body before JSON parsing
  • a secure place to store the webhook signing secret returned at creation

​
Register a webhook

Use the TypeScript client when you are already using the SDK: 
import { ApiClient } from '@cns-labs/agreements-api-client';

const client = new ApiClient({
  environment: 'testnet',
  apiKey: process.env.API_KEY,
});

const created = await client.createWebhook({
  url: 'https://example.com/shodai/webhooks',
  eventTypes: ['agreement.transitioned', 'agreement.notification.triggered'],
  filters: {
    templateIds: ['did:template:service-retainer-v0-1'],
  },
});

console.log(created.id);
console.log(created.secret);
The create response includes secret once. Store it immediately in your application’s secret manager.
Shodai does not include the signing secret when you list, get, update, disable, or test webhook subscriptions. If the secret was not stored from the create response, create a new webhook subscription.
For raw HTTP integrations, call POST /v0/webhooks with the same url, optional eventTypes, and optional filters fields. Use the generated Webhooks pages in the API Reference group for exact request and response schemas.

​
Choose event types

On create, omitted, null, or empty eventTypes defaults the subscription to agreement.transitioned. On update, omitted eventTypes leaves the existing event types unchanged. An explicit empty or null eventTypes value resets the subscription to agreement.transitioned. Subscribe to agreement.notification.triggered only when your integration also attaches external_webhook notification rules to agreements. A subscription alone does not create notification-triggered events. See Notification webhooks.

​
Verify deliveries

Prefer the SDK receiver helper instead of hand-rolling signature verification: 
import {
  constructWebhookEvent,
  WebhookVerificationError,
} from '@cns-labs/agreements-api-client/webhooks';

export async function receiveWebhook(request: Request) {
  const rawBody = await request.text();

  try {
    const event = constructWebhookEvent(
      rawBody,
      request.headers,
      process.env.SHODAI_WEBHOOK_SECRET!,
    );

    await storeWebhookEvent(event);
    return new Response(null, { status: 204 });
  } catch (error) {
    if (error instanceof WebhookVerificationError) {
      return Response.json({ error: 'invalid_webhook' }, { status: 400 });
    }
    throw error;
  }
}
Verify the raw request body before trusting parsed JSON. The helper checks:
  • x-shodai-webhook-id
  • x-shodai-webhook-timestamp
  • x-shodai-webhook-signature
  • timestamp tolerance, which defaults to 300 seconds
  • event envelope shape, supported apiVersion, supported event type, and header/body event ID match
The signature header uses sha256=<hex>. The signed message is ${timestamp}.${rawBody}, where timestamp is the x-shodai-webhook-timestamp header and rawBody is the exact request body bytes. Shodai signs the message with HMAC-SHA256 and the subscription secret.

​
Respond to deliveries

Return a 2xx response only after signature verification and durable receipt. A common pattern is:
  1. verify the signature with constructWebhookEvent(...)
  2. insert the event into durable storage keyed by event id
  3. treat duplicate event IDs as already received
  4. return 2xx
  5. process business side effects asynchronously
Your application owns deduplication, queueing, business side effects, logging, and observability.

​
Understand the event envelope

Every webhook delivery uses the same event envelope: 
{
  "id": "evt_123",
  "type": "agreement.transitioned",
  "apiVersion": "2026-06-01",
  "createdAt": "2026-06-02T18:00:00.000Z",
  "data": {}
}
The data shape depends on type.
  • agreement.transitioned contains compact transition data. See Agreement activity webhooks.
  • agreement.notification.triggered contains interpolated notification content for one resolved rule-recipient pair. See Notification webhooks.
  • webhook.test contains an empty data object.

​
Filter deliveries

Filters apply before delivery. Filter values are exact string matches. Multiple values inside one filter field act like OR. Different filter fields combine like AND. Empty or omitted filters mean all subscribed events for the API principal.
Filteragreement.transitionedagreement.notification.triggered
agreementIdsMatches data.agreementId.Matches data.agreementId.
templateIdsMatches data.templateId.Matches data.templateId.
inputIdsMatches data.inputId.Matches data.transition.inputId when the notification payload has transition data.
fromStatesMatches data.fromState.Matches data.transition.fromState when the notification payload has transition data.
toStatesMatches data.toState.Matches data.transition.toState when the notification payload has transition data.
ruleIdsNot used for agreement activity events.Matches data.ruleId.
Temporal notification webhooks do not include a transition block. They do not match inputIds, fromStates, or toStates filters.

​
Test a webhook

Use client.testWebhook(...) or POST /v0/webhooks/{id}/test to send a real signed webhook.test delivery to the subscription URL: 
const result = await client.testWebhook(created.id);

console.log(result.ok);
console.log(result.deliveryId);
console.log(result.status);
The test response reports the immediate delivery attempt. ok is true only when that attempt succeeds. Failed tests can include status, responseStatus, and error. Disabled subscriptions cannot be tested.

​
Disable a webhook

Use client.deleteWebhook(webhookId) or DELETE /v0/webhooks/{id} to disable a subscription: 
const disabled = await client.deleteWebhook(created.id);

console.log(disabled.status);
The route disables the subscription and returns the subscription with status: "disabled". It does not hard-delete the subscription record.

​
Handle failures and retries

Delivery status depends on your receiver response:
Receiver resultShodai behavior
2xxMarks the delivery as succeeded.
Network failure or no responseRetries when attempts remain.
5xxRetries when attempts remain.
4xxMarks the delivery as failed.
By default, Shodai makes up to 5 total delivery attempts. Retry scheduling is checked about every 60 seconds. Backoff starts at 60 seconds and doubles, capped at 60 minutes. Redirects are not followed. If a subscription is disabled or missing before a retry, the pending delivery is marked failed.

​
Use public HTTPS URLs

Webhook URLs must be valid HTTP or HTTPS URLs and must not include credentials. In normal hosted usage, Shodai requires HTTPS and rejects localhost or private-network targets, including hosts that resolve to private addresses. For local development, expose your local receiver through a public HTTPS tunnel and register the tunnel URL.

​
Troubleshooting

ProblemWhat to check
Missing secretUse the secret stored from the create response. If it was not stored, create a new webhook subscription.
Signature mismatchVerify against the exact raw body and the correct subscription secret before JSON parsing.
Timestamp rejectedCheck receiver clock drift or pass an explicit tolerance to constructWebhookEvent(...) if your receiver needs one.
No activity events receivedCheck subscription status, filters, event types, API principal ownership, and whether the agreement belongs to the same principal.
No notification events receivedCheck subscription status, event types, deploy-time notificationTemplate, external_webhook rule channels, rule triggers, and recipient resolution.
Test failsInspect responseStatus and error. 4xx is terminal; network failures and 5xx can retry when attempts remain.
Local URL rejectedUse a public HTTPS tunnel for local development.