Description
Summary: Creates a new webhook subscription via the TextPeak API.
Details: This endpoint registers a new webhook that will receive event notifications from the TextPeak platform. When a specified trigger event occurs (e.g., message delivery), the platform sends an HTTP request to the configured URL with the event payload. You can customize the webhook's HTTP method, headers, retry behavior, and apply filters to limit which events are forwarded (e.g., only events from specific streams). Additional query parameters can also be appended to the webhook request using the params field. Webhooks can be created in an active or inactive state using the activated flag. Authentication is performed via a TextPeak API key passed in the Authorization header.
Authentication & Scopes
Authentication is handled via a TextPeak API key provided in the Authorization header. No OAuth scopes are defined; access is granted or denied based on the validity of the API key.
| Method | Details |
|---|---|
| API Key | Pass your TextPeak API key directly in the Authorization header value. |
Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Your TextPeak API key that authenticates the request. |
Content-Type | Yes | Must be set to application/json. The API only accepts JSON-formatted request bodies. |
accept | Yes | Must be set to application/json. Indicates that the client expects a JSON response. |
Parameters
This endpoint does not use path or query parameters.
Request Body
The request body is a JSON object defining the webhook subscription configuration.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | A human-readable name for the webhook (e.g., "API test", "Delivery Notifications"). |
url | string | Yes | The destination URL that will receive the webhook event payloads (e.g., "https://textpeak.commpeak.com"). |
webhookTrigger | string | Yes | The event type that triggers the webhook. Defines which platform events will fire this webhook (e.g., "MESSAGE_DELIVERY"). |
method | string | Yes | The HTTP method used when sending the webhook request to the destination URL (e.g., "POST", "GET"). |
filter | object | No | An object containing filter criteria to limit which events trigger the webhook. Only events matching the filter will be forwarded. |
params | object | No | An object of key-value pairs appended as additional parameters to the webhook request (e.g., {"send_bulk": 1}). |
headers | object | No | An object of custom HTTP headers to include in the webhook request sent to the destination URL (e.g., {"x-example": "blablabla"}). |
retries | integer | No | The number of retry attempts if the webhook delivery fails. Set to 0 for no retries (e.g., 5). |
activated | boolean | Yes | Whether the webhook is active and will receive events. Set to true to enable or false to create in a disabled state. |
Filter Object
| Field | Type | Description |
|---|---|---|
stream_id | array | An array of stream IDs to filter events by. Only events originating from the specified streams will trigger the webhook (e.g., [3]). |
Examples
This endpoint has a saved example demonstrating usage:
- Create Webhook — Creating a webhook subscription with a trigger, filters, custom headers, retry configuration, and activation status.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||