TextKitDocs

Create a webhook endpoint

Registers a URL to receive events.

POST/v1/webhooks

Body Parameters

  • urlstring (uri)required

    Example: https://example.com/webhooks/textkit.

  • events* or array of string

    Event types to receive. Omit, or send "*" or [], for every event. An unknown type is a 400.

  • descriptionstring

    At most 120 characters.

  • numbersarray of string

    Optional. Only events about these of your numbers (E.164): message events by their from/to, number events by phone_number. Events about no number (batches, credits, registrations) go only to endpoints without a filter. Omit or [] for every number. At most 100 items.

Details

Same rules as the console: https only, a publicly reachable host, known event types, at most 5 endpoints per account. The response includes secret, the signing secret: this is the only time the API returns it.

Recorded in the audit log as webhook.created. Scope: webhooks:write.

Responses

  • 201WebhookEndpoint

    The endpoint, with its signing secret (shown once)

  • 401Error

    Missing, malformed, or revoked API key

  • 402Error

    Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged

  • 429Error

    Rate limit or quota exceeded

Response Fields

  • idstring

    Example: we_a1B2c3D4e5F6.

  • objectwebhook_endpoint
  • urlstring (uri)
  • events* or array of string
  • numbersarray of string

    The number filter: only events about these numbers. Empty: every number.

  • activeboolean
  • modetest, live

    Which events it receives: the mode of the key that created it (or chosen in the console). A key lists and changes only its own mode's endpoints.

  • descriptionstring

    Nullable.

  • created_atstring (date-time)
  • secretstring

    Example: whsec_a1B2c3D4e5F6g7H8a1B2c3D4e5F6g7H8.

Errors

Every error has the same JSON shape, and request_id matches the X-Request-Id response header. Errors lists every code and what to do about it.

  • 401

    Missing, malformed, or revoked API key

  • 402

    Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged

  • 429

    Rate limit or quota exceeded