> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shodai.network/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

For the complete documentation index, see [llms.txt](https://docs.shodai.network/llms.txt).

Create a signed webhook endpoint for agreement activity and notification events. The signing secret is returned only in the create response.


## OpenAPI

````yaml /openapi.json post /v0/webhooks
openapi: 3.1.0
info:
  title: Agreements API
  version: v0
  description: Author, deploy, read, and advance agreements through the Agreements API.
servers:
  - url: https://test-api.shodai.network
    description: Public base URL for the Agreements API testnet environment.
  - url: https://api.shodai.network
    description: Public base URL for the Agreements API production environment.
security: []
tags:
  - name: Agreement Records
    description: List and read agreement records.
  - name: Agreement Documents
    description: Resolve hosted agreement prose documents.
  - name: Authoring
    description: Check authored agreement JSON before deployment.
  - name: Deployment
    description: Preflight and deploy agreements.
  - name: Using Agreements
    description: Read state, inspect input history, and submit signed inputs.
  - name: Webhooks
    description: Register signed push callbacks for agreement events.
  - name: Wallet Access
    description: Prove control of a wallet and link it to the authenticated Shodai account.
  - name: System
    description: Health and OpenAPI discovery endpoints.
paths:
  /v0/webhooks:
    post:
      tags:
        - Webhooks
      summary: Create webhook
      description: >-
        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.
      operationId: createWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
            examples:
              webhook:
                summary: Webhook registration
                value:
                  url: https://example.com/shodai/webhooks
                  eventTypes:
                    - agreement.transitioned
                    - agreement.notification.triggered
                  filters:
                    templateIds:
                      - did:template:service-retainer-v0-1
      responses:
        '201':
          description: Created webhook subscription.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    $ref: '#/components/schemas/CreateWebhookResponse'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              examples:
                created:
                  summary: Created webhook subscription with one-time signing secret
                  value:
                    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
                      requestId: req_123
        '400':
          description: Invalid webhook registration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: >-
            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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            The credential lacks the required OAuth scope, the account lacks
            entitlement, or the account cannot access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
        - OAuthBearerAuth: []
components:
  schemas:
    CreateWebhookRequest:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: HTTPS endpoint that receives signed webhook POSTs.
        eventTypes:
          type: array
          items:
            type: string
            enum:
              - agreement.transitioned
              - agreement.notification.triggered
          description: >-
            Subscribable event types. On create, omitted, null, or empty
            eventTypes defaults to agreement.transitioned.
        filters:
          anyOf:
            - $ref: '#/components/schemas/WebhookFilters'
            - type: 'null'
          description: >-
            On create, omitted, null, or an empty object all mean no filters,
            and the subscription receives every event it is subscribed to.
      example:
        url: https://example.com/shodai/webhooks
        eventTypes:
          - agreement.transitioned
          - agreement.notification.triggered
        filters:
          templateIds:
            - did:template:service-retainer-v0-1
    CreateWebhookResponse:
      allOf:
        - $ref: '#/components/schemas/WebhookSubscription'
        - type: object
          required:
            - secret
          properties:
            secret:
              type: string
              description: >-
                Webhook signing secret. Store it immediately; it is returned
                only on creation.
      example:
        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
    ResponseMeta:
      type: object
      required:
        - apiVersion
        - requestId
      properties:
        apiVersion:
          type: string
          example: v0
        requestId:
          type: string
          description: Correlation ID for support and debugging.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - requestId
          properties:
            code:
              type: string
              example: unauthorized
              description: Stable machine-readable error code.
            message:
              type: string
              example: Missing API credential
              description: Safe human-readable error summary.
            details:
              description: Optional field errors or upstream-safe context.
            requestId:
              type: string
              description: Correlation ID for support and debugging.
    WebhookFilters:
      type: object
      properties:
        agreementIds:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string
            minLength: 1
            pattern: ^(?!\s)(?![\s\S]*\s$)[\s\S]+$
        templateIds:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string
            minLength: 1
            pattern: ^(?!\s)(?![\s\S]*\s$)[\s\S]+$
        inputIds:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string
            minLength: 1
            pattern: ^(?!\s)(?![\s\S]*\s$)[\s\S]+$
        fromStates:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string
            minLength: 1
            pattern: ^(?!\s)(?![\s\S]*\s$)[\s\S]+$
        toStates:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string
            minLength: 1
            pattern: ^(?!\s)(?![\s\S]*\s$)[\s\S]+$
        ruleIds:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string
            minLength: 1
            pattern: ^(?!\s)(?![\s\S]*\s$)[\s\S]+$
      description: >-
        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.
    WebhookSubscription:
      type: object
      required:
        - id
        - principalId
        - createdByApiKeyId
        - url
        - status
        - eventTypes
        - filters
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          description: Webhook subscription ID.
        principalId:
          type: string
          description: >-
            Identifier of the authenticated Shodai account that owns this
            webhook.
        createdByApiKeyId:
          anyOf:
            - type: string
            - type: 'null'
          description: API key that created the webhook, for audit only.
        url:
          type: string
          format: uri
          description: HTTPS endpoint that receives signed webhook POSTs.
        status:
          type: string
          enum:
            - active
            - disabled
          description: Webhook subscription status.
        eventTypes:
          type: array
          items:
            type: string
            enum:
              - agreement.transitioned
              - agreement.notification.triggered
          description: Subscribable event types this webhook can receive.
        filters:
          anyOf:
            - $ref: '#/components/schemas/WebhookFilters'
            - type: 'null'
          description: >-
            Filters applied before delivery. Null when the subscription has no
            filters and receives every event it is subscribed to.
        createdAt:
          type: string
          format: date-time
          description: Webhook creation timestamp.
        updatedAt:
          type: string
          format: date-time
          description: Webhook update timestamp.
      example:
        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'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Canonical API-key credential. Send X-API-Key: cns_pk_..., or
        Authorization: Bearer cns_pk_... only as an API-key compatibility alias.
      x-default: YOUR_API_KEY
    OAuthBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth access token issued by Shodai.
      x-default: Bearer YOUR_OAUTH_ACCESS_TOKEN

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.