Webhooks and Events
Configure Instance Webhook
Manages the instance webhooks. Supports simple mode (no action) and multi-webhook mode (with action: add/update/delete). To delete, send id + action "delete". Events come DISABLED by default. Enable only the ones you will consume (avoids unnecessary traffic). Only enable high-volume events (presence, history) if you will actually handle them.
POST
https://api.zapzapapi.com/api/v1/{instanceId}/webhookAuthentication with the x-api-key and x-api-secret headers.
Parameters
| Name | Type | In | Required | Description |
|---|---|---|---|---|
id | text | body | No | Unique webhook ID (required for update/delete) |
enabled | select | body | No | Enables/disables the webhook |
url | text | body | Yes | URL to receive the events |
events | json | body | No | List of events you want to receive on your webhook. EVERYTHING comes disabled by default: send only the ones you will use. Available: connection (connection), messages (received/sent messages), messages_update (status: delivered/read), history (history on connect, HIGH VOLUME), newsletter_messages (channel messages), call (calls), contacts, groups, chats, labels, chat_labels, presence (online/typing, HIGH VOLUME), blocks (blocks), sender. Example: ["messages","connection","messages_update"]. |
excludeMessages | json | body | No | Filters to exclude message types |
addUrlEvents | select | body | No | Adds the event type as a URL parameter. - `false` (default): normal URL - `true`: adds the event to the URL (e.g. `/webhook/message`) |
addUrlTypesMessages | select | body | No | Adds the message type as a URL parameter. - `false` (default): normal URL - `true`: adds the message type (e.g. `/webhook/conversation`) |
action | select | body | No | Action to perform: - add: create a new webhook - update: update an existing webhook (requires id) - delete: remove a webhook (requires only id) If omitted, operates in simple mode (single webhook) |
Request example
curl
curl -X POST "https://api.zapzapapi.com/api/v1/{instanceId}/webhook" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-api-secret: YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/webhook"}'Node.js
const res = await fetch("https://api.zapzapapi.com/api/v1/{instanceId}/webhook", {
method: "POST",
headers: {
"x-api-key": "YOUR_API_KEY",
"x-api-secret": "YOUR_API_SECRET",
"Content-Type": "application/json",
},
body: JSON.stringify({
"url": "https://example.com/webhook"
}),
});
console.log(await res.json());Python
import requests
res = requests.post(
"https://api.zapzapapi.com/api/v1/{instanceId}/webhook",
headers={"x-api-key": "YOUR_API_KEY", "x-api-secret": "YOUR_API_SECRET"},
json={"url":"https://example.com/webhook"},
)
print(res.json())Response example
JSON
{
"status": "Webhook deleted successfully"
}Values are illustrative; the fields follow the real response format.
Other endpoints in this category
Get your API keys
Create your account, connect a number in minutes and start using the API. R$15 per active number/month, with a welcome credit when you create the account, subject to the current campaign.