# WhatsApp webhooks

Forward WhatsApp messages and statuses to your own URL, instantly, with a debounce or at intervals.

Source: https://ardumaker.com/en/docs/webhooks-whatsapp/

- Category: Communication
- Status: Available
- Requirements: A [WhatsApp](https://ardumaker.com/en/docs/whatsapp-business-api) account in the company; A URL that accepts POST with JSON
- MCP tools (Read only): `listar_numeros_whatsapp`
- MCP tools (Write or modify): `crear_webhook_whatsapp`, `editar_webhook_whatsapp`, `simular_mensaje_sandbox_whatsapp`
- MCP tools (Destructive): `eliminar_webhook_whatsapp`

## What can you do with it?

Set up one or more URLs that receive incoming messages and status changes for all numbers in the account. It is the piece that connects WhatsApp to your own bot.

## When should you use it?

- A bot has to answer messages.
- Another system needs to record conversations.
- You want to group several consecutive messages from a contact before processing them.

## How does it work in ArduMaker?

| Mode | When it sends |
| --- | --- |
| `instant` | As soon as the message is ready. An audio goes out once its transcription finishes. |
| `debounce` | After `debounce_seconds` without new messages in that chat (0 to 3600, default 10). |
| `interval` | Every `interval_seconds`, with all pending chats (0 to 86400, default 60). |

The body is JSON with the account, the mode and a list of conversations (`headers`) with their messages. Files arrive as a signed public URL; the internal file path is never sent. `send_incoming` and `send_status` choose what is sent.

With `notify_audio_received` the webhook gets an immediate notice with `"event": "audio_received"` and the `X-Event: audio_received` header, before transcription. The final message comes later, without `event`.

## What actually changes?

- The webhook configuration is stored in the company's WhatsApp account.
- Each delivery is recorded per message, with HTTP status, duration and platform wait.
- A test message adds `"sandbox": true` and the `X-Sandbox: 1` header; a manual resend adds `"resend": true`.

## Diagram

**Incoming message to the webhook**

```text
WhatsApp
  ↓
Twilio (notifies ArduMaker)
  ↓
ArduMaker (stores and transcribes audio)
  ↓
Delivery by mode (instant, debounce or interval)
  ↓
Your URL (POST with JSON)
```

In `instant` delivery goes out right away; a periodic sweep is the safety net and never sends the same message twice.

## Expected result

Your server receives each message once. The chat shows how long each delivery took and which status the webhook returned.

## Errors and troubleshooting

- **The webhook was down**: automatic delivery does not repeat. From the chat, a specific message can be resent to the webhooks; resending does not alter what is pending.
- **Audio counted twice**: the `audio_received` notice and the final message are two POSTs; tell them apart by `event`.
- **400 `invalid_data`**: some field is invalid; the response names which.
- **Why my webhook rejects something**: the sandbox returns the status and body each webhook answered with.

## MCP access

Requires access to the company. See [/mcp/docs](https://ardumaker.com/en/mcp/docs).

| Type | Tools |
| --- | --- |
| Read | `listar_numeros_whatsapp` |
| Modify | `crear_webhook_whatsapp`, `editar_webhook_whatsapp`, `simular_mensaje_sandbox_whatsapp` |
| Destructive | `eliminar_webhook_whatsapp` |

> **PRECAUCION:** A webhook receives real customer traffic: whoever changes the URL decides where messages go. To pause it, use `editar_webhook_whatsapp` with `is_active=false` instead of deleting it.

## Related features

- [WhatsApp Business API](https://ardumaker.com/en/docs/whatsapp-business-api/)
- [Chat history](https://ardumaker.com/en/docs/historial-de-chats/)
- [Router IA](https://ardumaker.com/en/docs/router-ia/)