Subscribe an HTTPS endpoint to record events on one object.

Subscribe an HTTPS endpoint to record events on one object.

After this call, each event in events on a record of object_slug sends a signed POST to target_url. The response carries signing_secret, which you use to verify deliveries. It is returned only here, so store it before you do anything else.

The subscription belongs to the API key or OAuth app that created it, and only that credential can list, read or delete it. name is optional and defaults to the object name and the target host.

Scope: read.<object_slug> on the watched object.

Errors:

• 400 — an entry in events is not a catalog event name.
• 403 — the credential lacks read.<object_slug>, or the caller is a user session rather than an API key or OAuth token.
• 404 — no object has that slug.
• 422 — the body is invalid, for example target_url is not an HTTPS URL or events is empty.

Request:

{
  "object_slug": "contacts",
  "events": ["record.created", "record.updated"],
  "target_url": "https://hooks.example.com/corteksa",
  "name": "Contacts sync"
}

Response 201:

{
  "status": 201,
  "message": "Webhook subscription created. Copy the signing secret now — it will not be shown again.",
  "data": {
    "signing_secret": "whsec_4f9b2c7d1e8a3b6c5d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a",
    "subscription": {
      "slug": "b7e41c9a2f06",
      "name": "Contacts sync",
      "target_url": "https://hooks.example.com/corteksa",
      "object_slug": "contacts",
      "events": ["record.created", "record.updated"],
      "is_active": true,
      "created_at": "2026-09-14T10:00:00.000Z"
    }
  }
}