Receive webhooks

Webhooks are the signed delivery mechanism Shodai uses to send compact events to your backend. A webhook subscription belongs to a Shodai account, 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

Concept	Event type	Use it for
Webhooks	N/A	Shared subscription, signing, delivery, retry, test, and filtering infrastructure.
Agreement activity webhooks	`agreement.transitioned`	Mirroring or reconciling agreement lifecycle changes.
Notification webhooks	`agreement.notification.triggered`	Receiving rule-fired notification content after Shodai evaluates notification templates.
Test deliveries	`webhook.test`	Testing 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. agreement.transitioned is delivered for every finalized input, including inputs that do not change the state name: such deliveries carry fromState equal to toState. Treat the event as “a finalized input advanced this agreement”, not strictly “the state name changed” — it is the signal to re-read agreement state and input history. Notification rules are unaffected: they fire only on genuine state entry. Webhook deliveries are informational. Do not trigger value transfers or other irreversible actions from a delivery alone: on-chain value movement belongs in the agreement’s own on-chain actions, where the chain enforces it, and anything irreversible on your side should be confirmed against on-chain state rather than a delivered event payload.

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 Shodai account. The API-key path uses /v0/webhooks, while the Developer Portal uses your signed-in account. If a webhook is created with an API key, createdByApiKeyId is audit context, not the ownership boundary. The response field principalId identifies the owning Shodai account. Webhook management requires webhooks.read and webhooks.write access for the account. 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 '@shodai-network/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 '@shodai-network/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:

verify the signature with constructWebhookEvent(...)
insert the event into durable storage keyed by event id
treat duplicate event IDs as already received
return 2xx
process business side effects asynchronously

Your application owns deduplication, queueing, business side effects, logging, and observability. The event id is an opaque deterministic delivery identity. Retries and redeliveries for the same subscription carry the same id and payload; store it as an idempotency key instead of parsing its format. Delivery remains at-least-once, so duplicate attempts are expected.

Understand the event envelope

Every webhook delivery uses the same event envelope:

{
  "id": "effect_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "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 account. A supplied filter key must contain at least one non-blank value; an empty array or an array containing a blank or whitespace-only member is rejected with 400.

Filter	`agreement.transitioned`	`agreement.notification.triggered`
`agreementIds`	Matches `data.agreementId`.	Matches `data.agreementId`.
`templateIds`	Matches `data.templateId`.	Matches `data.templateId`.
`inputIds`	Matches `data.inputId`.	Matches `data.transition.inputId` when the notification payload has transition data.
`fromStates`	Matches `data.fromState`.	Matches `data.transition.fromState` when the notification payload has transition data.
`toStates`	Matches `data.toState`.	Matches `data.transition.toState` when the notification payload has transition data.
`ruleIds`	Not 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 result	Shodai behavior
`2xx`	Marks the delivery as succeeded.
Network failure or no response	Retries when attempts remain.
`5xx`	Retries when attempts remain.
`4xx`	Marks 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

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

Agreement activity webhooks
Notification webhooks
TypeScript client
Authentication
Use the Webhooks pages in the API Reference group for generated endpoint schemas.

Start

Workflow

Webhooks

Architecture

Examples

Reference

Webhook taxonomy

How webhooks are managed

Before you start

Register a webhook

Choose event types

Verify deliveries

Respond to deliveries

Understand the event envelope

Filter deliveries

Test a webhook

Disable a webhook

Handle failures and retries

Use public HTTPS URLs

Troubleshooting

​Webhook taxonomy

​How webhooks are managed

​Before you start

​Register a webhook

​Choose event types

​Verify deliveries

​Respond to deliveries

​Understand the event envelope

​Filter deliveries

​Test a webhook

​Disable a webhook

​Handle failures and retries

​Use public HTTPS URLs

​Troubleshooting

​Related pages

Webhook taxonomy

How webhooks are managed

Before you start

Register a webhook

Choose event types

Verify deliveries

Respond to deliveries

Understand the event envelope

Filter deliveries

Test a webhook

Disable a webhook

Handle failures and retries

Use public HTTPS URLs

Troubleshooting

Related pages