Skip to main content
POST
/
v0
/
webhooks
Create webhook
curl --request POST \
  --url https://test-api.shodai.network/v0/webhooks \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "url": "https://example.com/shodai/webhooks"
}
'
{
  "data": {
    "id": "wh_123",
    "principalId": "principal_123",
    "url": "https://example.com/shodai/webhooks",
    "status": "active",
    "eventTypes": [
      "agreement.transitioned",
      "agreement.notification.triggered"
    ],
    "filters": {
      "templateIds": [
        "did:template:service-retainer-v0-1"
      ],
      "ruleIds": [
        "deployment-follow-up"
      ]
    },
    "createdAt": "2026-05-26T16:00:00.000Z",
    "updatedAt": "2026-05-26T16:00:00.000Z",
    "secret": "whsec_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  },
  "meta": {
    "apiVersion": "v0",
    "requestId": "req_123"
  }
}
Create a signed webhook endpoint for agreement activity and notification events. The signing secret is returned only in the create response.

Authorizations

​
X-API-Key
string
header
default:YOUR_API_KEY
required

Canonical API-key credential. Send X-API-Key: cns_pk_..., or Authorization: Bearer cns_pk_... only as an API-key compatibility alias. OAuth and JWT bearer tokens are not supported.

Body

application/json
​
url
string<uri>
required

HTTPS endpoint that receives signed webhook POSTs.

​
eventTypes
enum<string>[]

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

Available options:
agreement.transitioned,
agreement.notification.triggered
​
filters
object

Optional filters applied before delivery. agreementIds and templateIds apply to both agreement.transitioned and agreement.notification.triggered. inputIds, fromStates, and toStates apply to agreement.transitioned and to notification events with transition data. ruleIds apply to agreement.notification.triggered events.

Response

Created webhook subscription.

​
data
object
required
Example:
{
  "id": "wh_123",
  "principalId": "principal_123",
  "url": "https://example.com/shodai/webhooks",
  "status": "active",
  "eventTypes": [
    "agreement.transitioned",
    "agreement.notification.triggered"
  ],
  "filters": {
    "templateIds": ["did:template:service-retainer-v0-1"],
    "ruleIds": ["deployment-follow-up"]
  },
  "createdAt": "2026-05-26T16:00:00.000Z",
  "updatedAt": "2026-05-26T16:00:00.000Z",
  "secret": "whsec_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}
​
meta
object
required