POST
/
webhooks
curl --request POST \
  --url https://api.trench.dev/webhooks \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://your-webhook-url.com",
  "enableBatching": true,
  "eventTypes": [
    "page",
    "track",
    "identify",
    "group"
  ],
  "eventNames": [
    "UserSignedUp",
    "UserLoggedIn"
  ],
  "flatten": true
}'
{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "url": "https://your-webhook-url.com",
  "enableBatching": true,
  "createdAt": "2021-01-01T00:00:00.000Z",
  "eventTypes": [
    "page",
    "track",
    "identify",
    "group"
  ],
  "eventNames": [
    "UserSignedUp",
    "UserLoggedIn"
  ],
  "flatten": true
}
This endpoint requires your private API key.

Once a webhook is created, events will be sent to it based on the criteria specified in the webhook. The data sent follows the Event schema and is sent as a JSON array in the POST request in the data field. Below is an example request body:

{
  "data": [
    {
      "uuid": "b99b40c5-e306-4351-9f1d-9a13bb9e8bd1",
      "type": "track",
      "event": "ConnectedAccount",
      "userId": "123e4567-e89b-12d3-a456-426614174000",
      "properties": {
        "totalAccounts": 4
      },
      "timestamp": "2024-10-21T21:32:17.000Z",
      "parsedAt": "2024-10-21T21:32:23.194Z"
    }
  ]
}

Body

application/json
​
url
string
required

The URL that the webhook will send events to.

Example:

"https://your-webhook-url.com"

​
enableBatching
boolean

Whether to enable batching for the webhook. Defaults to false.

Example:

true

​
eventTypes
string[]

The event types that the webhook will send. Defaults to ["*"] (all event types).

Example:
["page", "track", "identify", "group"]
​
eventNames
string[]

The event names that the webhook will send. Defaults to ["*"] (all event names).

Example:
["UserSignedUp", "UserLoggedIn"]
​
flatten
boolean

Whether to flatten the event data. This is useful for downstream systems that don't support nested data structures. Defaults to false.

Example:

true

Response

200 - application/json
The webhook has been successfully created. Requires private API key in Bearer token.
​
uuid
string
required

The UUID of the webhook. Automatically generated.

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
url
string
required

The URL that the webhook will send events to.

Example:

"https://your-webhook-url.com"

​
enableBatching
boolean
required

Whether to enable batching for the webhook.

Example:

true

​
createdAt
string
required

The date and time the webhook was created.

Example:

"2021-01-01T00:00:00.000Z"

​
eventTypes
string[]
required

The event types that the webhook will send. Use * to match all event types.

Example:
["page", "track", "identify", "group"]
​
eventNames
string[]
required

The event names that the webhook will send. Use * to match all event names.

Example:
["UserSignedUp", "UserLoggedIn"]
​
flatten
boolean
required

Whether to flatten the event data. This is useful for downstream systems that don't support nested data structures.

Example:

true

Was this page helpful?