Create a webhook subscription

Your Company APIWebhook subscriptions

POSThttps://api.your-company.example/v1/webhook-subscriptions

AuthenticationRequires bearerAuth.

Description

Creates a signed event delivery destination and returns its signing secret once.

Request

curl -X POST "https://api.your-company.example/v1/webhook-subscriptions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://contracts.example-counterparty.example/hooks/your-company",
  "events": [
    "matter.turn_completed",
    "matter.executed",
    "approval.requested"
  ]
}'

const response = await fetch("https://api.your-company.example/v1/webhook-subscriptions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
      "url": "https://contracts.example-counterparty.example/hooks/your-company",
      "events": [
        "matter.turn_completed",
        "matter.executed",
        "approval.requested"
      ]
    }),
});

import requests

response = requests.post(
    "https://api.your-company.example/v1/webhook-subscriptions",
    headers={
      "Authorization": "Bearer YOUR_TOKEN",
      "Content-Type": "application/json"
    },
    json={
      "url": "https://contracts.example-counterparty.example/hooks/your-company",
      "events": [
        "matter.turn_completed",
        "matter.executed",
        "approval.requested"
      ]
    },
)

Response201JSON

{
  "id": "whs_01JAZ92C4Q",
  "url": "https://contracts.example-counterparty.example/hooks/your-company",
  "events": [
    "matter.turn_completed",
    "matter.executed",
    "approval.requested"
  ],
  "status": "active",
  "created_at": "2026-07-01T17:10:00Z",
  "signing_secret": "whsec_••••••••••••••••"
}

Request body

application/jsonrequired

urlstring <uri>required

Public HTTPS delivery destination.

eventsstring[]required

Responses

201The created subscription. Store the signing secret securely because it is not shown again.application/json

idstringrequired

urlstring <uri>required

eventsstring[]required

statusstringrequired

Allowed values: activepaused

created_atstring <date-time>required

signing_secretstringrequired

Secret shown only in this response.

Example response

{
  "id": "whs_01JAZ92C4Q",
  "url": "https://contracts.example-counterparty.example/hooks/your-company",
  "events": [
    "matter.turn_completed",
    "matter.executed",
    "approval.requested"
  ],
  "status": "active",
  "created_at": "2026-07-01T17:10:00Z",
  "signing_secret": "whsec_••••••••••••••••"
}

401The API key is missing, malformed, expired, or revoked.application/json

errorobjectrequired

Object fields

codestringrequired

Stable machine-readable error code.

messagestringrequired

Human-readable summary.

request_idstringrequired

Identifier to include in a support ticket.

detailsobject[]

Array item fields

fieldstringrequired

Request field with an issue.

issuestringrequired

Human-readable validation problem.

Example response

{
  "error": {
    "code": "unauthorized",
    "message": "Provide a valid bearer API key.",
    "request_id": "req_01JAZA0P8M"
  }
}

403The API key does not have permission for this action.application/json

errorobjectrequired

Object fields

codestringrequired

Stable machine-readable error code.

messagestringrequired

Human-readable summary.

request_idstringrequired

Identifier to include in a support ticket.

detailsobject[]

Array item fields

fieldstringrequired

Request field with an issue.

issuestringrequired

Human-readable validation problem.

Example response

{
  "error": {
    "code": "forbidden",
    "message": "This API key does not have the required permission.",
    "request_id": "req_01JAZA0P8M"
  }
}

422One or more request fields are invalid.application/json

errorobjectrequired

Object fields

codestringrequired

Stable machine-readable error code.

messagestringrequired

Human-readable summary.

request_idstringrequired

Identifier to include in a support ticket.

detailsobject[]

Array item fields

fieldstringrequired

Request field with an issue.

issuestringrequired

Human-readable validation problem.

Example response

{
  "error": {
    "code": "validation_error",
    "message": "Correct the highlighted request fields.",
    "request_id": "req_01JAZA0P8M",
    "details": [
      {
        "field": "target_signature_date",
        "issue": "must be today or later"
      }
    ]
  }
}