Webhooks

Webhooks allow us to push raw events we collect about your emails over to your servers. Batches of events are delivered through a POST request to the defined target URL. You can use this endpoint to create and manage webhooks, or you can create one from the app.

Batch Information

• Any webhook batch that does not receive an HTTP 200 response will be retried for a total of 8 hours before the data is discarded.

• Each webhook batch contains the header X-MessageSystems-Batch-ID, which is useful for detecting and prevention of processing duplicate batches. Additionally within each event the event_id is unique and can also be used in duplicate detection and prevention.

• Webhooks posting to your endpoint will timeout after 10 seconds. For best results, write webhook batches to disk and then process asynchronously to minimize data loss if you have a problem with your database.

• Webhook batch status is available for 24 hours via the UI or the API.

• See Best Practices for Managing Webhook Data Streams for more information on how best to consume webhooks.

• See Webhook Authentication and Security for highly recommended security measures.

Event Types

You can receive any of the following types of events in webhook payloads:

• Message Status Events:

  • injection: Message was accepted for delivery

  • delivery: Message was successfully delivered

  • delay: Message delivery was delayed

  • bounce: Message delivery failed

  • spam_complaint: Recipient marked message as spam

  • out_of_band: Message bounced after initial acceptance

  • policy_rejection: Message was rejected by policy

  • generation_failure: Message generation failed

  • generation_rejection: Message was rejected during generation

• Recipient Engagement Events:

  • open: Message was opened

  • initial_open: First time message was opened

  • click: Link in message was clicked

  • initial_click: First time a link was clicked

  • amp_click: Link in AMP version was clicked

  • amp_open: AMP version was opened

List all Webhooks

get

Returns a list of all your webhooks.

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Responses

200

Successfully retrieved webhooks list

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/webhooks HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved webhooks list

{
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "target": "text",
      "events": [
        "text"
      ],
      "auth_type": "text",
      "auth_request_details": {},
      "auth_credentials": {},
      "last_successful": "2025-06-30T16:30:59.477Z",
      "last_failure": "2025-06-30T16:30:59.477Z",
      "active": true,
      "links": [
        {
          "href": "text",
          "rel": "text",
          "method": [
            "text"
          ]
        }
      ]
    }
  ]
}

Create a Webhook

post

Create a new webhook. When a webhook is created, a test POST request is sent to the target URL. If this request does not receive an HTTP 200 response, your request will fail with HTTP 400 and the webhook will not be created. If created successfully, the webhook will begin to receive event data after 1 minute.

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Body

namestringRequired

Name for webhook

targetstringRequired

URL of the target to which to POST event batches

eventsstring[]Required

Array of event types this webhook will send

activebooleanOptional

The status of the webhook

Default: true

custom_headersobjectOptional

Object of custom headers to be used during POST requests to target

auth_typestring · enumOptional

Type of authentication to be used during POST requests to target

Default: nonePossible values:

Responses

200

Webhook created successfully

application/json

400

Request validation error

application/json

post

HTTPcURLJavaScriptPython

POST /api/workspaces/{workspaceId}/reach/webhooks HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 207

{
  "name": "text",
  "target": "text",
  "events": [
    "text"
  ],
  "active": true,
  "custom_headers": {},
  "auth_type": "none",
  "auth_request_details": {
    "url": "text",
    "body": {}
  },
  "auth_credentials": {
    "username": "text",
    "password": "text"
  }
}

{
  "results": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "links": [
      {
        "href": "text",
        "rel": "text",
        "method": [
          "text"
        ]
      }
    ]
  }
}

Retrieve a Webhook

get

Retrieve a specific webhook by ID.

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

webhookIdstring · uuidRequired

The ID of the webhook

Responses

200

Successfully retrieved webhook

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/webhooks/{webhookId} HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved webhook

{
  "results": {
    "name": "text",
    "target": "text",
    "events": [
      "text"
    ],
    "auth_type": "text",
    "auth_request_details": {},
    "auth_credentials": {},
    "active": true,
    "links": [
      {
        "href": "text",
        "rel": "text",
        "method": [
          "text"
        ]
      }
    ]
  }
}

Update a Webhook

put

Update an existing webhook. If you change the target URL, a test POST request will be sent. If this request does not receive an HTTP 200 response, your request will fail with HTTP 400.

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

webhookIdstring · uuidRequired

The ID of the webhook

Body

namestringOptional

Name for webhook

targetstringOptional

URL of the target to which to POST event batches

eventsstring[]Optional

Array of event types this webhook will send

activebooleanOptional

The status of the webhook

custom_headersobjectOptional

Object of custom headers to be used during POST requests to target

auth_typestring · enumOptional

Type of authentication to be used during POST requests to target

Possible values:

auth_request_detailsobjectOptional

Object containing details needed for OAuth 2.0 authentication

auth_credentialsobjectOptional

Object containing credentials for Basic Authentication

Responses

200

Webhook updated successfully

application/json

400

Request validation error

application/json

put

HTTPcURLJavaScriptPython

PUT /api/workspaces/{workspaceId}/reach/webhooks/{webhookId} HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 150

{
  "name": "text",
  "target": "text",
  "events": [
    "text"
  ],
  "active": true,
  "custom_headers": {},
  "auth_type": "none",
  "auth_request_details": {},
  "auth_credentials": {}
}

{
  "results": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "links": [
      {
        "href": "text",
        "rel": "text",
        "method": [
          "text"
        ]
      }
    ]
  }
}

Delete a Webhook

delete

Delete a specific webhook by ID.

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

webhookIdstring · uuidRequired

The ID of the webhook

Responses

204

Webhook deleted successfully

delete

HTTPcURLJavaScriptPython

DELETE /api/workspaces/{workspaceId}/reach/webhooks/{webhookId} HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

204

Webhook deleted successfully

No content

Validate a Webhook

post

The validation request sends an example message event batch to the target URL, validates that the target responds with HTTP 200, and returns information on the response received.

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

webhookIdstring · uuidRequired

The ID of the webhook

Responses

200

Webhook validation successful

application/json

post

HTTPcURLJavaScriptPython

POST /api/workspaces/{workspaceId}/reach/webhooks/{webhookId}/validate HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Webhook validation successful

{
  "results": {
    "msg": "text",
    "response": {
      "status": 1,
      "headers": {},
      "body": "text"
    }
  }
}

Retrieve Batch Status Information

get

Get status information about webhook batches. Status information is provided for failed batches and those that succeeded on retry. Batch status is available for 24 hours.

Authorizations

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

webhookIdstring · uuidRequired

The ID of the webhook

Query parameters

limitintegerOptional

Maximum number of results to return

Default: 1000

Responses

200

Successfully retrieved batch status information

application/json

get

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/webhooks/{webhookId}/batch-status HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved batch status information

{
  "results": [
    {
      "batch_id": "text",
      "ts": "2025-06-30T16:30:59.477Z",
      "attempts": 1,
      "response_code": "text",
      "failure_code": "text",
      "latency": 1
    }
  ]
}