Webhooks

Create a webhook

Registers a new webhook endpoint to receive real-time events. Choose a source (messaging / user / account_status / post) and supply the target URL. The HMAC signing secret is returned exactly once in the 201 response, store it securely.

post/v1/webhooks

Request

  • Base URL: https://api.curviate.com
  • URL: https://api.curviate.com/v1/webhooks
  • Auth: HTTP bearer

Request body

OR
OR
OR

Response

Webhook registered. The HMAC signing secret is returned exactly once, store it immediately.

object'webhook'

Response type discriminator.

idstring

Webhook id (wh_-prefixed ULID).

source'messaging' | 'user' | 'account_status' | 'post'

The event source this webhook subscribes to.

request_urlstring

The URL that receives delivery POST requests.

namestring nullable

Human-readable label.

account_idsstring[] nullable

Accounts targeted by this webhook (acc_ ids you own), or null when an account_status webhook covers every current and future account.

enabledboolean

A disabled webhook is created but delivers nothing.

eventsstring[]

Canonical event names this webhook subscribes to.

datastring[]

Field-remapping keys for the delivery payload (messaging and user sources only; post and account_status have none).

secretstring

HMAC signing secret, 64 hexadecimal characters, returned exactly once at creation. Store it securely.

secret_prefixstring

The first 8 characters of the secret, for identification without exposing it. Exactly the value the read endpoints return for this webhook.

created_atstring

ISO-8601 creation timestamp.

Example response

{
  "secret": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
  "secret_prefix": "a1b2c3d4",
  "safety_warning": {
    "row": "profile_views",
    "reset_at": "2026-09-05T00:00:00.000Z",
    "hint": {
      "parameter": "profile_views.ceiling",
      "message": "This account is at its ceiling for profile_views. This action went through because profile_views.posture is warn, and it counted: 101 of 100 this window. Raise profile_views.ceiling, or wait for the window to reset at 2026-09-05T00:00:00.000Z."
    },
    "reason": "ceiling",
    "blocked": false
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.