Ir para o conteúdo
WhatsMarketingDeveloper Hub

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
curl "https://micuenta.whatsmarketing.es/api/v1/webhooks/events" \
  -H "Authorization: Bearer $WM_API_KEY"
Node.js
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();
Python
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
<?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);
Resposta 200
[
  {
    "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
curl "https://micuenta.whatsmarketing.es/api/v1/webhooks" \
  -H "Authorization: Bearer $WM_API_KEY"
Node.js
const res = await fetch('https://micuenta.whatsmarketing.es/api/v1/webhooks', {
  headers: {
    Authorization: `Bearer ${process.env.WM_API_KEY}`,
  },
});
const data = await res.json();
Python
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
<?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);
Resposta 200
[
  {
    "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

NomeTipoValores
url obrigatóriostring0–500 caracteres
events obrigatóriostring[]≤ 20

Erros frequentes

  • 400 WEBHOOK_URL_NOT_PUBLIC A URL aponta para um endereço privado ou local.
  • 403 A chave não tem webhooks:write ou não foi criada por um administrador.
  • 403 WEBHOOK_EVENT_SCOPE_MISSING A chave não pode ler os dados de algum dos eventos.
  • 409 WEBHOOKS_LIMIT Já existem 10 webhooks: cancele algum.
curl
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"
  ]
}'
Node.js
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();
Python
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
<?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);
Resposta 201
{
  "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

NomeOndeTipoValores
id obrigatóriorotastring
curl
curl "https://micuenta.whatsmarketing.es/api/v1/webhooks/{id}" \
  -H "Authorization: Bearer $WM_API_KEY"
Node.js
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();
Python
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
<?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);
Resposta 200
{
  "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

NomeOndeTipoValores
id obrigatóriorotastring
curl
curl -X DELETE "https://micuenta.whatsmarketing.es/api/v1/webhooks/{id}" \
  -H "Authorization: Bearer $WM_API_KEY"
Node.js
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();
Python
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
<?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);
Resposta 200
{
  "id": "8c7b6a5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d",
  "deleted": true
}