API reference

Webhooks

Endpoints, test events, delivery history and replay.

Register a webhook endpoint. The signing secret is shown only once.#

POST/webhook-endpoints

Authentication: API key (Bearer pk_…), or console session (Bearer ses_… with the X-Environment-Id header)
Required scope: webhooks:manage

Request body (JSON)

Field	Type		Description
`url`	string	required	https URL of your receiver. http, localhost and private-network addresses are rejected.
`events`	string[]	required	`*` to receive everything

Example

bash

curl -X POST "$INBOX_API/webhook-endpoints" \
  -H "Authorization: Bearer $INBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/webhooks/inbox",
    "events": [
      "message.received",
      "message.delivered",
      "message.failed"
    ]
  }'

javascript

const res = await fetch(`${process.env.INBOX_API}/webhook-endpoints`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INBOX_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "url": "https://api.example.com/webhooks/inbox",
    "events": [
      "message.received",
      "message.delivered",
      "message.failed"
    ]
  }),
});
const data = await res.json();

python

import os
import requests

res = requests.post(
    f"{os.environ['INBOX_API']}/webhook-endpoints",
    headers={
        "Authorization": f"Bearer {os.environ['INBOX_KEY']}",
    },
    json={
        "url": "https://api.example.com/webhooks/inbox",
        "events": [
            "message.received",
            "message.delivered",
            "message.failed",
        ],
    },
)
print(res.json())

php

<?php

$ch = curl_init(getenv('INBOX_API') . '/webhook-endpoints');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('INBOX_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'url' => 'https://api.example.com/webhooks/inbox',
        'events' => [
            'message.received',
            'message.delivered',
            'message.failed',
        ],
    ]),
]);
$data = json_decode(curl_exec($ch), true);

Response · 201 Created

{
  "id": "bc06ae32-7564-46d5-89fb-a9869019aa8e",
  "url": "https://api.example.com/webhooks/inbox",
  "events": [
    "message.received",
    "message.delivered",
    "message.failed"
  ],
  "status": "active",
  "consecutiveFailures": 0,
  "disabledReason": null,
  "createdAt": "2026-11-12T08:33:45.704Z",
  "secret": "whsec_b4ac869893324714f88bfd25026b3e2e2891bb8c087"
}

List endpoints#

GET/webhook-endpoints

Authentication: API key (Bearer pk_…), or console session (Bearer ses_… with the X-Environment-Id header)
Required scope: webhooks:manage

Example

bash

curl "$INBOX_API/webhook-endpoints" \
  -H "Authorization: Bearer $INBOX_KEY"

javascript

const res = await fetch(`${process.env.INBOX_API}/webhook-endpoints`, {
  headers: {
    Authorization: `Bearer ${process.env.INBOX_KEY}`,
  },
});
const data = await res.json();

python

import os
import requests

res = requests.get(
    f"{os.environ['INBOX_API']}/webhook-endpoints",
    headers={
        "Authorization": f"Bearer {os.environ['INBOX_KEY']}",
    },
)
print(res.json())

php

<?php

$ch = curl_init(getenv('INBOX_API') . '/webhook-endpoints');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('INBOX_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);

Response · 200 OK

[
  {
    "id": "bc06ae32-7564-46d5-89fb-a9869019aa8e",
    "url": "https://api.example.com/webhooks/inbox",
    "events": [
      "message.received",
      "message.delivered",
      "message.failed"
    ],
    "status": "active",
    "consecutiveFailures": 0,
    "disabledReason": null,
    "createdAt": "2026-11-12T08:33:45.704Z"
  }
]

Get an endpoint#

GET/webhook-endpoints/{id}

Authentication: API key (Bearer pk_…), or console session (Bearer ses_… with the X-Environment-Id header)
Required scope: webhooks:manage

Parameters

Name	Location	Type	Description
`id`required	path	string	Endpoint ID.

Example

bash

curl "$INBOX_API/webhook-endpoints/ID" \
  -H "Authorization: Bearer $INBOX_KEY"

javascript

const res = await fetch(`${process.env.INBOX_API}/webhook-endpoints/ID`, {
  headers: {
    Authorization: `Bearer ${process.env.INBOX_KEY}`,
  },
});
const data = await res.json();

python

import os
import requests

res = requests.get(
    f"{os.environ['INBOX_API']}/webhook-endpoints/ID",
    headers={
        "Authorization": f"Bearer {os.environ['INBOX_KEY']}",
    },
)
print(res.json())

php

<?php

$ch = curl_init(getenv('INBOX_API') . '/webhook-endpoints/ID');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('INBOX_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);

Response · 200 OK

{
  "id": "bc06ae32-7564-46d5-89fb-a9869019aa8e",
  "url": "https://api.example.com/webhooks/inbox",
  "events": [
    "message.received",
    "message.delivered",
    "message.failed"
  ],
  "status": "active",
  "consecutiveFailures": 0,
  "disabledReason": null,
  "createdAt": "2026-11-12T08:33:45.704Z"
}

Update the URL and events, or disable/re-enable#

PATCH/webhook-endpoints/{id}

Authentication: API key (Bearer pk_…), or console session (Bearer ses_… with the X-Environment-Id header)
Required scope: webhooks:manage

Parameters

Name	Location	Type	Description
`id`required	path	string	Endpoint ID.

Request body (JSON)

Field	Type		Description
`url`	string	optional	https URL of your receiver. http, localhost and private-network addresses are rejected.
`events`	string[]	optional	Events received: `*` for everything, or a list of message.received, message.sent, message.delivered, message.read, message.failed, template.status_updated.
`enabled`	boolean	optional	false = disable, true = re-enable (resets the failure counter to zero)

Example

bash

curl -X PATCH "$INBOX_API/webhook-endpoints/ID" \
  -H "Authorization: Bearer $INBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      "*"
    ]
  }'

javascript

const res = await fetch(`${process.env.INBOX_API}/webhook-endpoints/ID`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.INBOX_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "events": [
      "*"
    ]
  }),
});
const data = await res.json();

python

import os
import requests

res = requests.patch(
    f"{os.environ['INBOX_API']}/webhook-endpoints/ID",
    headers={
        "Authorization": f"Bearer {os.environ['INBOX_KEY']}",
    },
    json={
        "events": [
            "*",
        ],
    },
)
print(res.json())

php

<?php

$ch = curl_init(getenv('INBOX_API') . '/webhook-endpoints/ID');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('INBOX_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'events' => [
            '*',
        ],
    ]),
]);
$data = json_decode(curl_exec($ch), true);

Response · 200 OK

{
  "id": "bc06ae32-7564-46d5-89fb-a9869019aa8e",
  "url": "https://api.example.com/webhooks/inbox",
  "events": [
    "*"
  ],
  "status": "active",
  "consecutiveFailures": 0,
  "disabledReason": null,
  "createdAt": "2026-11-12T08:33:45.704Z"
}

Delete an endpoint (its past deliveries are kept until the end of the retention period)#

DELETE/webhook-endpoints/{id}

Authentication: API key (Bearer pk_…), or console session (Bearer ses_… with the X-Environment-Id header)
Required scope: webhooks:manage

Parameters

Name	Location	Type	Description
`id`required	path	string	Endpoint ID.

Example

bash

curl -X DELETE "$INBOX_API/webhook-endpoints/ID" \
  -H "Authorization: Bearer $INBOX_KEY"

javascript

const res = await fetch(`${process.env.INBOX_API}/webhook-endpoints/ID`, {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.INBOX_KEY}`,
  },
});
const data = res.status;

python

import os
import requests

res = requests.delete(
    f"{os.environ['INBOX_API']}/webhook-endpoints/ID",
    headers={
        "Authorization": f"Bearer {os.environ['INBOX_KEY']}",
    },
)
print(res.status_code)

php

<?php

$ch = curl_init(getenv('INBOX_API') . '/webhook-endpoints/ID');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('INBOX_KEY'),
    ],
]);
curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE);

Response · 204 No Content

(no content)

Generate a new signing secret (the old one stops working)#

POST/webhook-endpoints/{id}/rotate-secret

Authentication: API key (Bearer pk_…), or console session (Bearer ses_… with the X-Environment-Id header)
Required scope: webhooks:manage

Parameters

Name	Location	Type	Description
`id`required	path	string	Endpoint ID.

Example

bash

curl -X POST "$INBOX_API/webhook-endpoints/ID/rotate-secret" \
  -H "Authorization: Bearer $INBOX_KEY"

javascript

const res = await fetch(`${process.env.INBOX_API}/webhook-endpoints/ID/rotate-secret`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INBOX_KEY}`,
  },
});
const data = await res.json();

python

import os
import requests

res = requests.post(
    f"{os.environ['INBOX_API']}/webhook-endpoints/ID/rotate-secret",
    headers={
        "Authorization": f"Bearer {os.environ['INBOX_KEY']}",
    },
)
print(res.json())

php

<?php

$ch = curl_init(getenv('INBOX_API') . '/webhook-endpoints/ID/rotate-secret');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('INBOX_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);

Response · 201 Created

{
  "id": "bc06ae32-7564-46d5-89fb-a9869019aa8e",
  "url": "https://api.example.com/webhooks/inbox",
  "events": [
    "*"
  ],
  "status": "active",
  "consecutiveFailures": 0,
  "disabledReason": null,
  "createdAt": "2026-11-12T08:33:45.704Z",
  "secret": "whsec_c0dd380e9faa2e006a42d82e13b793a7db5a2a0c8d1"
}

Check the endpoint: sends a signed test event and returns the response#

POST/webhook-endpoints/{id}/test

Authentication: API key (Bearer pk_…), or console session (Bearer ses_… with the X-Environment-Id header)
Required scope: webhooks:manage

Parameters

Name	Location	Type	Description
`id`required	path	string	Endpoint ID.

Example

bash

curl -X POST "$INBOX_API/webhook-endpoints/ID/test" \
  -H "Authorization: Bearer $INBOX_KEY"

javascript

const res = await fetch(`${process.env.INBOX_API}/webhook-endpoints/ID/test`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INBOX_KEY}`,
  },
});
const data = await res.json();

python

import os
import requests

res = requests.post(
    f"{os.environ['INBOX_API']}/webhook-endpoints/ID/test",
    headers={
        "Authorization": f"Bearer {os.environ['INBOX_KEY']}",
    },
)
print(res.json())

php

<?php

$ch = curl_init(getenv('INBOX_API') . '/webhook-endpoints/ID/test');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('INBOX_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);

Response · 200 OK

{
  "ok": true,
  "statusCode": 200,
  "durationMs": 3,
  "error": null
}

Delivery history (paginated)#

GET/webhook-deliveries

Authentication: API key (Bearer pk_…), or console session (Bearer ses_… with the X-Environment-Id header)
Required scope: webhooks:manage

Parameters

Name	Location	Type	Description
`endpointId`	query	string	Filter by endpoint.
`status`	query	string	Filter by delivery status: pending, succeeded or failed.Values: pending, succeeded, failed
`limit`	query	number	Number of items per page, from 1 to 100.
`cursor`	query	string	`nextCursor` value from the previous page, to get the next one.

Example

bash

curl "$INBOX_API/webhook-deliveries" \
  -H "Authorization: Bearer $INBOX_KEY"

javascript

const res = await fetch(`${process.env.INBOX_API}/webhook-deliveries`, {
  headers: {
    Authorization: `Bearer ${process.env.INBOX_KEY}`,
  },
});
const data = await res.json();

python

import os
import requests

res = requests.get(
    f"{os.environ['INBOX_API']}/webhook-deliveries",
    headers={
        "Authorization": f"Bearer {os.environ['INBOX_KEY']}",
    },
)
print(res.json())

php

<?php

$ch = curl_init(getenv('INBOX_API') . '/webhook-deliveries');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('INBOX_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);

Response · 200 OK

{
  "data": [
    {
      "id": "473dfe39-7555-4942-8a5b-d2ec99026b44",
      "endpointId": "bc06ae32-7564-46d5-89fb-a9869019aa8e",
      "eventId": "2cbc3e2b-fba4-4246-868d-76ffe9fcb829",
      "eventType": "message.sent",
      "status": "succeeded",
      "attempts": 1,
      "lastStatusCode": 200,
      "lastError": null,
      "replayOf": null,
      "createdAt": "2026-11-12T08:33:46.267Z",
      "deliveredAt": "2026-11-12T08:33:46.324Z"
    },
    {
      "id": "bbc7a388-fa7b-4ef3-8a5c-fbf58564274d",
      "endpointId": "bc06ae32-7564-46d5-89fb-a9869019aa8e",
      "eventId": "868ce546-0caa-45f3-860b-0884eb112f39",
      "eventType": "message.sent",
      "status": "succeeded",
      "attempts": 1,
      "lastStatusCode": 200,
      "lastError": null,
      "replayOf": null,
      "createdAt": "2026-11-12T08:33:46.265Z",
      "deliveredAt": "2026-11-12T08:33:46.313Z"
    },
    {
      "id": "7a8b6205-9cf5-4ceb-8710-b0e1d029b2c1",
      "endpointId": "bc06ae32-7564-46d5-89fb-a9869019aa8e",
      "eventId": "8ff3994c-4406-4b8f-8f54-1ef9ee961cc0",
      "eventType": "message.sent",
      "status": "succeeded",
      "attempts": 1,
      "lastStatusCode": 200,
      "lastError": null,
      "replayOf": null,
      "createdAt": "2026-11-12T08:33:46.264Z",
      "deliveredAt": "2026-11-12T08:33:46.303Z"
    }
  ],
  "nextCursor": "MjAyNi0xMS0xMlQwODozMzo0Ni4yNjRafDU3MDEzYjE1LTM3ZmMtNDgwZC1hOTkyLWIxODhiMjNmZGE1MQ"
}

Get a delivery, with each attempt#

GET/webhook-deliveries/{id}

Authentication: API key (Bearer pk_…), or console session (Bearer ses_… with the X-Environment-Id header)
Required scope: webhooks:manage

Parameters

Name	Location	Type	Description
`id`required	path	string	Delivery ID.

Example

bash

curl "$INBOX_API/webhook-deliveries/ID" \
  -H "Authorization: Bearer $INBOX_KEY"

javascript

const res = await fetch(`${process.env.INBOX_API}/webhook-deliveries/ID`, {
  headers: {
    Authorization: `Bearer ${process.env.INBOX_KEY}`,
  },
});
const data = await res.json();

python

import os
import requests

res = requests.get(
    f"{os.environ['INBOX_API']}/webhook-deliveries/ID",
    headers={
        "Authorization": f"Bearer {os.environ['INBOX_KEY']}",
    },
)
print(res.json())

php

<?php

$ch = curl_init(getenv('INBOX_API') . '/webhook-deliveries/ID');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('INBOX_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);

Response · 200 OK

{
  "id": "473dfe39-7555-4942-8a5b-d2ec99026b44",
  "endpointId": "bc06ae32-7564-46d5-89fb-a9869019aa8e",
  "eventId": "2cbc3e2b-fba4-4246-868d-76ffe9fcb829",
  "eventType": "message.sent",
  "status": "succeeded",
  "attempts": 1,
  "lastStatusCode": 200,
  "lastError": null,
  "replayOf": null,
  "createdAt": "2026-11-12T08:33:46.267Z",
  "deliveredAt": "2026-11-12T08:33:46.324Z",
  "payload": {
    "data": {
      "to": "237611111111",
      "status": "sent",
      "messageId": "a9691d7a-ee51-4da9-87b2-24cce79a9313",
      "occurredAt": "2026-11-12T08:33:46.251Z",
      "waMessageId": "wamid.HBgMXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "phoneNumberId": "4d8e654e-d744-4bf3-8211-9ceffcccfe87"
    },
    "createdAt": "2026-11-12T08:33:46.247Z"
  },
  "attemptsDetail": [
    {
      "attempt": 1,
      "statusCode": 200,
      "error": null,
      "durationMs": 0,
      "responseSnippet": "ok",
      "at": "2026-11-12T08:33:46.322Z"
    }
  ]
}

Replay the event to the same endpoint#

POST/webhook-deliveries/{id}/replay

Authentication: API key (Bearer pk_…), or console session (Bearer ses_… with the X-Environment-Id header)
Required scope: webhooks:manage

Parameters

Name	Location	Type	Description
`id`required	path	string	Delivery ID.

Example

bash

curl -X POST "$INBOX_API/webhook-deliveries/ID/replay" \
  -H "Authorization: Bearer $INBOX_KEY"

javascript

const res = await fetch(`${process.env.INBOX_API}/webhook-deliveries/ID/replay`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INBOX_KEY}`,
  },
});
const data = await res.json();

python

import os
import requests

res = requests.post(
    f"{os.environ['INBOX_API']}/webhook-deliveries/ID/replay",
    headers={
        "Authorization": f"Bearer {os.environ['INBOX_KEY']}",
    },
)
print(res.json())

php

<?php

$ch = curl_init(getenv('INBOX_API') . '/webhook-deliveries/ID/replay');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('INBOX_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);

Response · 202 Accepted

{
  "id": "13980898-c6ac-4b7c-8e78-f68fd741cfb9",
  "endpointId": "bc06ae32-7564-46d5-89fb-a9869019aa8e",
  "eventId": "2cbc3e2b-fba4-4246-868d-76ffe9fcb829",
  "eventType": "message.sent",
  "status": "pending",
  "attempts": 0,
  "lastStatusCode": null,
  "lastError": null,
  "replayOf": "473dfe39-7555-4942-8a5b-d2ec99026b44",
  "createdAt": "2026-11-12T08:33:46.391Z",
  "deliveredAt": null
}