Webhooks

Create webhook

Registers a signed webhook endpoint for subscribed agreement activity and notification events visible to the authenticated Shodai account. The signing secret is returned only in the create response.

post/v0/webhooks

Request

  • Base URL: https://test-api.shodai.network
  • URL: https://test-api.shodai.network/v0/webhooks
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer

Request body

urlstring uri required

HTTPS endpoint that receives signed webhook POSTs.

eventTypesstring[]

Subscribable event types. On create, omitted, null, or empty eventTypes defaults to agreement.transitioned.

Example request

{
  "url": "https://example.com/shodai/webhooks",
  "eventTypes": [
    "agreement.transitioned",
    "agreement.notification.triggered"
  ],
  "filters": {
    "templateIds": [
      "did:template:service-retainer-v0-1"
    ]
  }
}

Response

Created webhook subscription.

Example response

{
  "data": {
    "id": "wh_123",
    "principalId": "account_123",
    "createdByApiKeyId": null,
    "url": "https://example.com/shodai/webhooks",
    "status": "active",
    "eventTypes": [
      "agreement.transitioned",
      "agreement.notification.triggered"
    ],
    "filters": {
      "templateIds": [
        "did:template:service-retainer-v0-1"
      ]
    },
    "createdAt": "2026-05-26T16:00:00.000Z",
    "updatedAt": "2026-05-26T16:00:00.000Z",
    "secret": "whsec_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  },
  "meta": {
    "apiVersion": "v0"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.