---
title: "Create webhook"
method: POST
path: "/v0/webhooks"
tags: ["Webhooks"]
---

# Create webhook

`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

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.

## Request body

- CreateWebhookRequest
  - `url` string, uri, required: HTTPS endpoint that receives signed webhook POSTs.
  - `eventTypes` string[]: Subscribable event types. On create, omitted, null, or empty eventTypes defaults to agreement.transitioned.
  - `filters` WebhookFilters: 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. A filter key you supply must constrain something: an empty array, an array containing a blank or whitespace-only member, or a value with leading or trailing whitespace is rejected with 400. Values must be unique after trimming. To subscribe without any filters, send filters as null or as an empty object. Deploy transitions carry the payload value fromState: "" but are filtered with inputIds: ["__deploy"]; "" is not accepted as a filter value.
    - `agreementIds` string[]
    - `templateIds` string[]
    - `inputIds` string[]
    - `fromStates` string[]
    - `toStates` string[]
    - `ruleIds` string[]

## Response `201`

Created webhook subscription.

- object
  - `data` CreateWebhookResponse, required
    - `id` string, required: Webhook subscription ID.
    - `principalId` string, required: Identifier of the authenticated Shodai account that owns this webhook.
    - `createdByApiKeyId` string, nullable, required: API key that created the webhook, for audit only.
    - `url` string, uri, required: HTTPS endpoint that receives signed webhook POSTs.
    - `status` 'active' | 'disabled', required: Webhook subscription status.
    - `eventTypes` string[], required: Subscribable event types this webhook can receive.
    - `filters` WebhookFilters, required: 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. A filter key you supply must constrain something: an empty array, an array containing a blank or whitespace-only member, or a value with leading or trailing whitespace is rejected with 400. Values must be unique after trimming. To subscribe without any filters, send filters as null or as an empty object. Deploy transitions carry the payload value fromState: "" but are filtered with inputIds: ["__deploy"]; "" is not accepted as a filter value.
      - `agreementIds` string[]
      - `templateIds` string[]
      - `inputIds` string[]
      - `fromStates` string[]
      - `toStates` string[]
      - `ruleIds` string[]
    - `createdAt` string, date-time, required: Webhook creation timestamp.
    - `updatedAt` string, date-time, required: Webhook update timestamp.
    - `secret` string, required: Webhook signing secret. Store it immediately; it is returned only on creation.
  - `meta` ResponseMeta, required
    - `apiVersion` string, required
    - `requestId` string, required: Correlation ID for support and debugging.

## Other responses

- `400`: Invalid webhook registration.
- `401`: Missing or invalid API credential.
- `402`: The authenticated Shodai account has paid_required entitlement mode for the requested scope. Per-call x402 settlement is not implemented. Treat this as an entitlement/operator issue.
- `403`: The credential lacks the required OAuth scope, the account lacks entitlement, or the account cannot access the resource.

---

[API](https://skmtc.dev/shodai/apis/agreements-api.md) · [All operations](https://skmtc.dev/shodai/apis/agreements-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shodai/apis/agreements-api/revisions/0ac329d0e9a0?raw)