Webhooks
Inscrever e cancelar webhooks a partir do seu sistema, como fazem os gatilhos do Zapier e do Make. Precisa de webhooks:write em uma chave criada por um administrador. Cada evento pede também a permissão dos dados que entrega (por exemplo, contact.created pede contacts:read; message.status, messages:send). Uma chave só vê e cancela os webhooks que ela mesma criou, e eles são apagados ao revogar a chave. Pausar, ver entregas e repetir se faz no painel. Veja o guia Webhooks.
Eventos disponíveis
GET/webhooks/events
A lista de eventos que um webhook pode assinar, com o nome legível.
Permissões: webhooks:write
curl "https://micuenta.whatsmarketing.es/api/v1/webhooks/events" \
-H "Authorization: Bearer $WM_API_KEY"const res = await fetch('https://micuenta.whatsmarketing.es/api/v1/webhooks/events', {
headers: {
Authorization: `Bearer ${process.env.WM_API_KEY}`,
},
});
const data = await res.json();import os, requests
r = requests.get(
"https://micuenta.whatsmarketing.es/api/v1/webhooks/events",
headers={"Authorization": f"Bearer {os.environ['WM_API_KEY']}"},
timeout=30,
)
r.raise_for_status()
data = r.json()<?php
$ch = curl_init('https://micuenta.whatsmarketing.es/api/v1/webhooks/events');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('WM_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);[
{
"key": "message.status",
"label": "Un mensaje enviado por API se entregó, se leyó o falló"
}
]Listar webhooks
GET/webhooks
Os webhooks que esta chave inscreveu, com o segredo mascarado e as entregas dos últimos 7 dias.
Permissões: webhooks:write
curl "https://micuenta.whatsmarketing.es/api/v1/webhooks" \
-H "Authorization: Bearer $WM_API_KEY"const res = await fetch('https://micuenta.whatsmarketing.es/api/v1/webhooks', {
headers: {
Authorization: `Bearer ${process.env.WM_API_KEY}`,
},
});
const data = await res.json();import os, requests
r = requests.get(
"https://micuenta.whatsmarketing.es/api/v1/webhooks",
headers={"Authorization": f"Bearer {os.environ['WM_API_KEY']}"},
timeout=30,
)
r.raise_for_status()
data = r.json()<?php
$ch = curl_init('https://micuenta.whatsmarketing.es/api/v1/webhooks');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('WM_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);[
{
"sent7d": 42,
"failed7d": 0,
"id": "8c7b6a5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d",
"url": "https://hooks.zapier.com/hooks/catch/123/abc/",
"maskedSecret": "whsec_1a2b…",
"events": [
"message.status"
],
"eventLabels": [
"Un mensaje enviado por API se entregó, se leyó o falló"
],
"status": "ACTIVE",
"failureStreak": 0,
"lastDeliveryAt": "2026-11-11T10:05:00.000Z",
"lastSuccessAt": "2026-11-11T10:05:00.000Z",
"createdAt": "2026-11-11T10:00:00.000Z"
}
]Inscrever um webhook
POST/webhooks
Uma URL https pública e os eventos. Responde com o webhook e o secret (whsec_…), que só é devolvido aqui: guarde-o para verificar a assinatura. Até 10 por organização e 10 inscrições por minuto.
Permissões: webhooks:write
Corpo da requisição CreateWebhook
| Nome | Tipo | Valores |
|---|---|---|
url obrigatório | string | 0–500 caracteres |
events obrigatório | string[] | ≤ 20 |
Erros frequentes
- 400
WEBHOOK_URL_NOT_PUBLICA URL aponta para um endereço privado ou local. - 403 A chave não tem
webhooks:writeou não foi criada por um administrador. - 403
WEBHOOK_EVENT_SCOPE_MISSINGA chave não pode ler os dados de algum dos eventos. - 409
WEBHOOKS_LIMITJá existem 10 webhooks: cancele algum.
curl -X POST "https://micuenta.whatsmarketing.es/api/v1/webhooks" \
-H "Authorization: Bearer $WM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.zapier.com/hooks/catch/123/abc/",
"events": [
"message.status"
]
}'const res = await fetch('https://micuenta.whatsmarketing.es/api/v1/webhooks', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.WM_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"url": "https://hooks.zapier.com/hooks/catch/123/abc/",
"events": [
"message.status"
]
}),
});
const data = await res.json();import os, requests
r = requests.post(
"https://micuenta.whatsmarketing.es/api/v1/webhooks",
headers={"Authorization": f"Bearer {os.environ['WM_API_KEY']}"},
json={
"url": "https://hooks.zapier.com/hooks/catch/123/abc/",
"events": [
"message.status"
]
},
timeout=30,
)
r.raise_for_status()
data = r.json()<?php
$ch = curl_init('https://micuenta.whatsmarketing.es/api/v1/webhooks');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('WM_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'url' => 'https://hooks.zapier.com/hooks/catch/123/abc/',
'events' => [
'message.status'
]
]),
]);
$data = json_decode(curl_exec($ch), true);{
"sent7d": 42,
"failed7d": 0,
"id": "8c7b6a5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d",
"url": "https://hooks.zapier.com/hooks/catch/123/abc/",
"maskedSecret": "whsec_1a2b…",
"events": [
"message.status"
],
"eventLabels": [
"Un mensaje enviado por API se entregó, se leyó o falló"
],
"status": "ACTIVE",
"failureStreak": 0,
"lastDeliveryAt": "2026-11-11T10:05:00.000Z",
"lastSuccessAt": "2026-11-11T10:05:00.000Z",
"createdAt": "2026-11-11T10:00:00.000Z",
"secret": "whsec_…"
}Ver um webhook
GET/webhooks/{id}
Um webhook com o segredo mascarado. 404 se esta chave não o inscreveu.
Permissões: webhooks:write
Parâmetros
| Nome | Onde | Tipo | Valores |
|---|---|---|---|
id obrigatório | rota | string |
curl "https://micuenta.whatsmarketing.es/api/v1/webhooks/{id}" \
-H "Authorization: Bearer $WM_API_KEY"const res = await fetch('https://micuenta.whatsmarketing.es/api/v1/webhooks/{id}', {
headers: {
Authorization: `Bearer ${process.env.WM_API_KEY}`,
},
});
const data = await res.json();import os, requests
r = requests.get(
"https://micuenta.whatsmarketing.es/api/v1/webhooks/{id}",
headers={"Authorization": f"Bearer {os.environ['WM_API_KEY']}"},
timeout=30,
)
r.raise_for_status()
data = r.json()<?php
$ch = curl_init('https://micuenta.whatsmarketing.es/api/v1/webhooks/{id}');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('WM_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);{
"sent7d": 42,
"failed7d": 0,
"id": "8c7b6a5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d",
"url": "https://hooks.zapier.com/hooks/catch/123/abc/",
"maskedSecret": "whsec_1a2b…",
"events": [
"message.status"
],
"eventLabels": [
"Un mensaje enviado por API se entregó, se leyó o falló"
],
"status": "ACTIVE",
"failureStreak": 0,
"lastDeliveryAt": "2026-11-11T10:05:00.000Z",
"lastSuccessAt": "2026-11-11T10:05:00.000Z",
"createdAt": "2026-11-11T10:00:00.000Z"
}Cancelar um webhook
DELETE/webhooks/{id}
Elimina o webhook com o histórico de entregas. É o que o Zapier ou o Make chamam ao desligar um gatilho.
Permissões: webhooks:write
Parâmetros
| Nome | Onde | Tipo | Valores |
|---|---|---|---|
id obrigatório | rota | string |
curl -X DELETE "https://micuenta.whatsmarketing.es/api/v1/webhooks/{id}" \
-H "Authorization: Bearer $WM_API_KEY"const res = await fetch('https://micuenta.whatsmarketing.es/api/v1/webhooks/{id}', {
method: 'DELETE',
headers: {
Authorization: `Bearer ${process.env.WM_API_KEY}`,
},
});
const data = await res.json();import os, requests
r = requests.delete(
"https://micuenta.whatsmarketing.es/api/v1/webhooks/{id}",
headers={"Authorization": f"Bearer {os.environ['WM_API_KEY']}"},
timeout=30,
)
r.raise_for_status()
data = r.json()<?php
$ch = curl_init('https://micuenta.whatsmarketing.es/api/v1/webhooks/{id}');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('WM_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);{
"id": "8c7b6a5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d",
"deleted": true
}