Référence API

Webhooks

Destinations, événements de test, historique des livraisons et rejeu.

Déclarer une destination de webhook. Le secret de signature n’est affiché qu’une fois.#

POST/webhook-endpoints

Authentification: Clé API (Bearer pk_…), ou session de la console (Bearer ses_… avec l'en-tête X-Environment-Id)
Portée requise: webhooks:manage

Corps de la requête (JSON)

Champ	Type		Description
`url`	string	requis	URL https de votre récepteur. Les adresses http, localhost et réseau privé sont refusées.
`events`	string[]	requis	`*` pour tout recevoir

Exemple

bash

curl -X POST "$INBOX_API/webhook-endpoints" \
  -H "Authorization: Bearer $INBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.exemple.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.exemple.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.exemple.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.exemple.com/webhooks/inbox',
        'events' => [
            'message.received',
            'message.delivered',
            'message.failed',
        ],
    ]),
]);
$data = json_decode(curl_exec($ch), true);

Réponse · 201 Created

{
  "id": "bc06ae32-7564-46d5-89fb-a9869019aa8e",
  "url": "https://api.exemple.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"
}

Lister les destinations#

GET/webhook-endpoints

Authentification: Clé API (Bearer pk_…), ou session de la console (Bearer ses_… avec l'en-tête X-Environment-Id)
Portée requise: webhooks:manage

Exemple

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);

Réponse · 200 OK

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

Détail d’une destination#

GET/webhook-endpoints/{id}

Authentification: Clé API (Bearer pk_…), ou session de la console (Bearer ses_… avec l'en-tête X-Environment-Id)
Portée requise: webhooks:manage

Paramètres

Nom	Emplacement	Type	Description
`id`requis	chemin	string	Identifiant de la destination.

Exemple

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);

Réponse · 200 OK

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

Modifier l’URL, les événements, ou désactiver/réactiver#

PATCH/webhook-endpoints/{id}

Authentification: Clé API (Bearer pk_…), ou session de la console (Bearer ses_… avec l'en-tête X-Environment-Id)
Portée requise: webhooks:manage

Paramètres

Nom	Emplacement	Type	Description
`id`requis	chemin	string	Identifiant de la destination.

Corps de la requête (JSON)

Champ	Type		Description
`url`	string	optionnel	URL https de votre récepteur. Les adresses http, localhost et réseau privé sont refusées.
`events`	string[]	optionnel	Événements reçus : `*` pour tout, ou une liste parmi message.received, message.sent, message.delivered, message.read, message.failed, template.status_updated.
`enabled`	boolean	optionnel	false = désactiver, true = réactiver (remet le compteur d’échecs à zéro)

Exemple

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);

Réponse · 200 OK

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

Supprimer une destination (ses livraisons passées sont conservées jusqu’à la fin de la rétention)#

DELETE/webhook-endpoints/{id}

Authentification: Clé API (Bearer pk_…), ou session de la console (Bearer ses_… avec l'en-tête X-Environment-Id)
Portée requise: webhooks:manage

Paramètres

Nom	Emplacement	Type	Description
`id`requis	chemin	string	Identifiant de la destination.

Exemple

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);

Réponse · 204 No Content

(aucun contenu)

Générer un nouveau secret de signature (l’ancien cesse de fonctionner)#

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

Authentification: Clé API (Bearer pk_…), ou session de la console (Bearer ses_… avec l'en-tête X-Environment-Id)
Portée requise: webhooks:manage

Paramètres

Nom	Emplacement	Type	Description
`id`requis	chemin	string	Identifiant de la destination.

Exemple

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);

Réponse · 201 Created

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

Vérifier la destination : envoie un événement de test signé et renvoie la réponse#

POST/webhook-endpoints/{id}/test

Authentification: Clé API (Bearer pk_…), ou session de la console (Bearer ses_… avec l'en-tête X-Environment-Id)
Portée requise: webhooks:manage

Paramètres

Nom	Emplacement	Type	Description
`id`requis	chemin	string	Identifiant de la destination.

Exemple

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);

Réponse · 200 OK

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

Historique des livraisons (paginé)#

GET/webhook-deliveries

Authentification: Clé API (Bearer pk_…), ou session de la console (Bearer ses_… avec l'en-tête X-Environment-Id)
Portée requise: webhooks:manage

Paramètres

Nom	Emplacement	Type	Description
`endpointId`	requête	string	Filtrer sur une destination.
`status`	requête	string	Filtrer par statut de livraison : pending, succeeded ou failed.Valeurs : pending, succeeded, failed
`limit`	requête	number	Nombre d'éléments par page, de 1 à 100.
`cursor`	requête	string	Valeur `nextCursor` de la page précédente, pour obtenir la suite.

Exemple

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);

Réponse · 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"
}

Détail d’une livraison, avec chaque tentative#

GET/webhook-deliveries/{id}

Authentification: Clé API (Bearer pk_…), ou session de la console (Bearer ses_… avec l'en-tête X-Environment-Id)
Portée requise: webhooks:manage

Paramètres

Nom	Emplacement	Type	Description
`id`requis	chemin	string	Identifiant de la livraison.

Exemple

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);

Réponse · 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"
    }
  ]
}

Rejouer l’événement vers la même destination#

POST/webhook-deliveries/{id}/replay

Authentification: Clé API (Bearer pk_…), ou session de la console (Bearer ses_… avec l'en-tête X-Environment-Id)
Portée requise: webhooks:manage

Paramètres

Nom	Emplacement	Type	Description
`id`requis	chemin	string	Identifiant de la livraison.

Exemple

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);

Réponse · 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
}