Webhooks

What are webhooks?

Webhooks are an efficient, automated way for one application to push data to another in real time. They let different systems communicate specific events without the receiving application having to poll for them. Instead, the application that generates the event sends a notification, usually an HTTP POST request, to a URL the receiving application configured in advance.

What do webhooks do?

Webhooks notify your application about events that happen in another application or service. Some common tasks handled by webhooks include:

Real-time notifications: the receiving application is notified immediately when something happens, such as a new order, a status change, or a new message.
Process automation: they let you automate responses or actions in your application when certain events happen, without constantly querying the API.
System integration: they make it easy to integrate different systems, letting events in one system trigger automatic actions in another.

How do webhooks work?

Setup: first, the receiving application sets up an endpoint (a public URL) ready to receive webhook notifications.
Webhook registration: the sending application is configured to send notifications to the webhook endpoint whenever a specific event happens.
Event delivery: when the configured event happens, the sending application sends an HTTP POST request to the webhook endpoint, including the relevant event data in the request body.
Event processing: the receiving application processes the received information and can take several actions in response, such as updating a database, sending an email, or triggering another internal process.

One webhook, many instances

A webhook on Zapster is a destination you register once (the URL that will receive events) and reuse across as many instances as you want. Each instance decides, on its own, which events it wants to receive at that destination. It helps to understand two concepts that work together:

The webhook (on your account): holds the URL, a name, and the status (on or off). It is the address notifications are sent to. It belongs to your account, not to a specific instance.
The association with each instance: every instance that uses the webhook gets its own association. That is where the subscribed events and per-instance settings live (enable/disable, test mode). The same webhook can be associated with several instances at once.

The main reason is centralized maintenance. If you have dozens of instances sending events to the same system, registering the URL once and reusing it avoids repeating configuration. When the URL needs to change (new server, new domain, route adjustment), you update it in one place and the change applies to every instance that uses that webhook.

How to do it in practice

The same endpoint (POST /wa/instances/:id/webhooks) covers both paths. The difference is in the request body:

Send url to create a new webhook and associate it with the instance right away. Use this for the first instance.
Send webhook_id to reuse a webhook that already exists. Use this for the remaining instances.

The body accepts url OR webhook_id, never both together. If both are sent, Zapster prioritizes webhook_id. The events field is always required and must have at least one event.

1. First instance: create the webhook with url

curl -X POST https://api.zapsterapi.com/v1/wa/instances/FIRST_INSTANCE/webhooks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhook",
    "name": "Production webhook",
    "events": ["message.received", "message.sent"]
  }'

const response = await fetch(
  'https://api.zapsterapi.com/v1/wa/instances/FIRST_INSTANCE/webhooks',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      url: 'https://your-app.com/webhook',
      name: 'Production webhook',
      events: ['message.received', 'message.sent'],
    }),
  },
);

const data = await response.json();
console.log(data);
// The response returns the id of the created webhook, which you reuse on the next instances.
// { "webhook_id": "2nenz69l0xbf0m3uu9tfo", ... }

// Node.js 18+ (native fetch). Keep the token in an environment variable.
const response = await fetch(
  'https://api.zapsterapi.com/v1/wa/instances/FIRST_INSTANCE/webhooks',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.ZAPSTER_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      url: 'https://your-app.com/webhook',
      name: 'Production webhook',
      events: ['message.received', 'message.sent'],
    }),
  },
);

const { webhook_id } = await response.json();
console.log('Webhook created:', webhook_id);

<?php
$ch = curl_init('https://api.zapsterapi.com/v1/wa/instances/FIRST_INSTANCE/webhooks');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_TOKEN',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'url' => 'https://your-app.com/webhook',
        'name' => 'Production webhook',
        'events' => ['message.received', 'message.sent'],
    ]),
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo $data['webhook_id'];

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	body, _ := json.Marshal(map[string]any{
		"url":    "https://your-app.com/webhook",
		"name":   "Production webhook",
		"events": []string{"message.received", "message.sent"},
	})

	req, _ := http.NewRequest(
		http.MethodPost,
		"https://api.zapsterapi.com/v1/wa/instances/FIRST_INSTANCE/webhooks",
		bytes.NewReader(body),
	)
	req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	data, _ := io.ReadAll(resp.Body)
	fmt.Println(string(data))
}

import requests

response = requests.post(
    "https://api.zapsterapi.com/v1/wa/instances/FIRST_INSTANCE/webhooks",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
        "url": "https://your-app.com/webhook",
        "name": "Production webhook",
        "events": ["message.received", "message.sent"],
    },
)

data = response.json()
print(data["webhook_id"])

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class CreateWebhook {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "url": "https://your-app.com/webhook",
              "name": "Production webhook",
              "events": ["message.received", "message.sent"]
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.zapsterapi.com/v1/wa/instances/FIRST_INSTANCE/webhooks"))
            .header("Authorization", "Bearer YOUR_TOKEN")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}

require "net/http"
require "json"
require "uri"

uri = URI("https://api.zapsterapi.com/v1/wa/instances/FIRST_INSTANCE/webhooks")

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer YOUR_TOKEN"
request["Content-Type"] = "application/json"
request.body = {
  url: "https://your-app.com/webhook",
  name: "Production webhook",
  events: ["message.received", "message.sent"]
}.to_json

response = http.request(request)
data = JSON.parse(response.body)
puts data["webhook_id"]

2. Remaining instances: reuse with webhook_id Use the webhook_id returned in the previous step to associate the same webhook with another instance. Note that the events can be different: each instance subscribes to what makes sense for it.

curl -X POST https://api.zapsterapi.com/v1/wa/instances/SECOND_INSTANCE/webhooks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_id": "2nenz69l0xbf0m3uu9tfo",
    "events": ["message.received"]
  }'

const response = await fetch(
  'https://api.zapsterapi.com/v1/wa/instances/SECOND_INSTANCE/webhooks',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      webhook_id: '2nenz69l0xbf0m3uu9tfo',
      events: ['message.received'],
    }),
  },
);

const data = await response.json();
console.log(data);

// Node.js 18+ (native fetch).
const response = await fetch(
  'https://api.zapsterapi.com/v1/wa/instances/SECOND_INSTANCE/webhooks',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.ZAPSTER_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      webhook_id: '2nenz69l0xbf0m3uu9tfo',
      events: ['message.received'],
    }),
  },
);

console.log(await response.json());

<?php
$ch = curl_init('https://api.zapsterapi.com/v1/wa/instances/SECOND_INSTANCE/webhooks');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_TOKEN',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'webhook_id' => '2nenz69l0xbf0m3uu9tfo',
        'events' => ['message.received'],
    ]),
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	body, _ := json.Marshal(map[string]any{
		"webhook_id": "2nenz69l0xbf0m3uu9tfo",
		"events":     []string{"message.received"},
	})

	req, _ := http.NewRequest(
		http.MethodPost,
		"https://api.zapsterapi.com/v1/wa/instances/SECOND_INSTANCE/webhooks",
		bytes.NewReader(body),
	)
	req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	data, _ := io.ReadAll(resp.Body)
	fmt.Println(string(data))
}

import requests

response = requests.post(
    "https://api.zapsterapi.com/v1/wa/instances/SECOND_INSTANCE/webhooks",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
        "webhook_id": "2nenz69l0xbf0m3uu9tfo",
        "events": ["message.received"],
    },
)

print(response.json())

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ReuseWebhook {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "webhook_id": "2nenz69l0xbf0m3uu9tfo",
              "events": ["message.received"]
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.zapsterapi.com/v1/wa/instances/SECOND_INSTANCE/webhooks"))
            .header("Authorization", "Bearer YOUR_TOKEN")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}

require "net/http"
require "json"
require "uri"

uri = URI("https://api.zapsterapi.com/v1/wa/instances/SECOND_INSTANCE/webhooks")

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer YOUR_TOKEN"
request["Content-Type"] = "application/json"
request.body = {
  webhook_id: "2nenz69l0xbf0m3uu9tfo",
  events: ["message.received"]
}.to_json

puts http.request(request).body

Editing and removing: what changes

Because the webhook and the association are distinct things, editing or removing has different scopes. It is worth knowing each operation before applying changes in production.

Operation	Endpoint	Scope	Effect
Create + associate new	`POST /wa/instances/:id/webhooks` with `url`	Instance	Creates a new webhook and associates it with the instance
Reuse existing	`POST /wa/instances/:id/webhooks` with `webhook_id`	Instance	Associates an existing webhook with one more instance
Edit the webhook	`PATCH /webhooks/:id` (url/name/enabled)	Account	Propagates to ALL associated instances
Edit the association	`PATCH /wa/instances/:id/webhooks/:whId` (events/enabled/test_mode)	Instance	Changes only that instance’s subscription
Disassociate	`DELETE /wa/instances/:id/webhooks/:whId`	Instance	Turns it off for that instance only; still active on the others
Delete	`DELETE /webhooks/:id`	Account	Removes it from ALL instances

Editing the webhook propagates to everyone. Changing the URL or the name through the account endpoint (PATCH /webhooks/:id) affects every associated instance. If you need a different URL for a single instance, create a new webhook instead of editing the existing one.

Disassociating is not the same as deleting. DELETE /wa/instances/:id/webhooks/:whId only turns the webhook off for that instance; it stays active on the others and on your account. To delete the webhook for good, use DELETE /webhooks/:id.

How to tell the origin apart on the receiver

Each instance delivers events independently, even when they share the same webhook. To know where each notification came from, use the HTTP headers:

X-Instance-ID: identifies the instance that generated the event (the real origin).
X-Webhook-ID: identifies the shared webhook that delivered the notification.

Because the subscribed events can differ per instance, the same webhook may receive message.received from one instance and message.sent from another. Always look at X-Instance-ID to route or log the event correctly. Sharing a webhook makes sense when:

All instances deliver to the same system (a CRM, a queue, a central endpoint).
You want to change the destination URL in one place in the future.
The processing on the receiver already uses X-Instance-ID to separate origins.

Separate webhooks per instance make more sense when:

Each instance belongs to a different customer or product, with its own URL.
You need to turn a single instance’s destination on or off without touching the others.
Separate environments (production and staging) must not mix.

Best practices

Store the webhook_id returned at creation; it is what you reuse on the next instances.
Use the webhook name to make its purpose clear (for example, “CRM production”).
On the receiver, treat X-Instance-ID as the source of truth for the event’s origin.
Before editing the URL of a shared webhook, confirm which instances will be affected with the list webhooks endpoint.

Frequently asked questions

Can I change one instance's URL without affecting the others?

Not through the webhook edit endpoint, which is account-scoped and propagates to every associated instance. For a dedicated URL, create a new webhook by sending url at creation and associate it with the desired instance only.

If I disassociate a webhook from an instance, does it disappear from the account?

No. DELETE /wa/instances/:id/webhooks/:whId only turns the webhook off for that instance. It stays active on the others and on your account. To delete it for good, use DELETE /webhooks/:id.

How do I know which instance sent each notification?

Through the X-Instance-ID header, present in every notification. X-Webhook-ID indicates the webhook that made the delivery.

Can I send `url` and `webhook_id` in the same request?

Send only one of them. If both are provided, Zapster prioritizes webhook_id and ignores url.

For the details of each endpoint, check the API reference: create/associate webhook, edit the instance association, disassociate from the instance, edit the webhook, and delete the webhook.

Failure handling and retries

In an ideal scenario, the receiving application receives and processes the webhook request without issues. However, failures can happen for various reasons, such as server downtime, network problems, or processing errors. To make sure important notifications are not lost, we implement a retry mechanism. If the receiving application responds with an HTTP status code greater than 400 (indicating an error), the sending application will retry the webhook notification up to 5 times.

Retry details

Failure criterion: any response with an HTTP status code greater than or equal to 400.
Number of retries: up to 5 attempts.
Interval between retries: the interval between each retry grows progressively with a factor of 2.5. The intervals in seconds are:
- 1st attempt: 2.5 seconds (2.5^1)
- 2nd attempt: ~6 seconds (2.5^2)
- 3rd attempt: ~15 seconds (2.5^3)
- 4th attempt: ~39 seconds (2.5^4)
- 5th attempt: ~97 seconds (2.5^5)
Each interval is calculated as 2.5^n, where n is the attempt number.

Custom HTTP headers

Every webhook notification sent by the Zapster API includes custom HTTP headers that identify the origin and context of the event. These headers are useful for validation, logging, and firewall rules.

Header	Type	Description	Example	Present in
`X-Instance-ID`	string	ID of the instance that generated the event	`inst_abc123`	Every notification
`X-Message-ID`	string	Unique ID of the notification	`msg_xyz789`	Every notification
`X-Webhook-ID`	string	ID of the registered webhook	`whk_def456`	When a webhook is registered
`X-Attempt-Count`	number	Attempt number (1-5)	`1`	Every notification
`User-Agent`	string	Sender identifier	`Zapsterapi/1.2.3`	Every notification

Validation and allowlisting

You can use the custom HTTP headers to validate the origin of received notifications. Because the webhook is delivered via POST to your server, the examples below show the receiving endpoint in each language (cURL and browser code do not receive webhooks, so they are not shown here):

// Node.js + Express
app.post('/webhook', (req, res) => {
  const instanceId = req.headers['x-instance-id']
  const messageId = req.headers['x-message-id']
  const attemptCount = req.headers['x-attempt-count']

  console.log(`Notification received from instance ${instanceId}`)
  console.log(`Message ID: ${messageId}, attempt: ${attemptCount}`)

  // Validate the origin before processing
  if (!instanceId) {
    return res.status(400).json({ error: 'Missing X-Instance-ID header' })
  }

  // Process the event
  const event = req.body
  console.log(`Event: ${event.type}`, event.data)

  res.status(200).json({ received: true })
})

<?php
// Headers arrive in $_SERVER with the HTTP_ prefix and underscores instead of hyphens
$instanceId = $_SERVER['HTTP_X_INSTANCE_ID'] ?? null;
$messageId = $_SERVER['HTTP_X_MESSAGE_ID'] ?? null;
$attemptCount = $_SERVER['HTTP_X_ATTEMPT_COUNT'] ?? null;

error_log("Notification received from instance {$instanceId}");
error_log("Message ID: {$messageId}, attempt: {$attemptCount}");

// Validate the origin before processing
if (!$instanceId) {
    http_response_code(400);
    echo json_encode(['error' => 'Missing X-Instance-ID header']);
    exit;
}

// Process the event
$event = json_decode(file_get_contents('php://input'), true);
error_log("Event: {$event['type']}");

http_response_code(200);
echo json_encode(['received' => true]);

package main

import (
	"encoding/json"
	"log"
	"net/http"
)

func webhookHandler(w http.ResponseWriter, r *http.Request) {
	instanceID := r.Header.Get("X-Instance-ID")
	messageID := r.Header.Get("X-Message-ID")
	attemptCount := r.Header.Get("X-Attempt-Count")

	log.Printf("Notification received from instance %s", instanceID)
	log.Printf("Message ID: %s, attempt: %s", messageID, attemptCount)

	// Validate the origin before processing
	if instanceID == "" {
		w.WriteHeader(http.StatusBadRequest)
		json.NewEncoder(w).Encode(map[string]string{"error": "Missing X-Instance-ID header"})
		return
	}

	// Process the event
	var event map[string]any
	json.NewDecoder(r.Body).Decode(&event)
	log.Printf("Event: %v", event["type"])

	w.WriteHeader(http.StatusOK)
	json.NewEncoder(w).Encode(map[string]bool{"received": true})
}

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.post("/webhook")
def webhook():
    instance_id = request.headers.get("X-Instance-ID")
    message_id = request.headers.get("X-Message-ID")
    attempt_count = request.headers.get("X-Attempt-Count")

    print(f"Notification received from instance {instance_id}")
    print(f"Message ID: {message_id}, attempt: {attempt_count}")

    # Validate the origin before processing
    if not instance_id:
        return jsonify(error="Missing X-Instance-ID header"), 400

    # Process the event
    event = request.get_json()
    print(f"Event: {event['type']}", event["data"])

    return jsonify(received=True), 200

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import java.util.Map;

@RestController
public class WebhookController {

    @PostMapping("/webhook")
    public ResponseEntity<?> receive(
            @RequestHeader(value = "X-Instance-ID", required = false) String instanceId,
            @RequestHeader(value = "X-Message-ID", required = false) String messageId,
            @RequestHeader(value = "X-Attempt-Count", required = false) String attemptCount,
            @RequestBody Map<String, Object> event) {

        System.out.printf("Notification received from instance %s%n", instanceId);
        System.out.printf("Message ID: %s, attempt: %s%n", messageId, attemptCount);

        // Validate the origin before processing
        if (instanceId == null) {
            return ResponseEntity.badRequest().body(Map.of("error", "Missing X-Instance-ID header"));
        }

        // Process the event
        System.out.println("Event: " + event.get("type"));

        return ResponseEntity.ok(Map.of("received", true));
    }
}

require "sinatra"
require "json"

post "/webhook" do
  instance_id = request.env["HTTP_X_INSTANCE_ID"]
  message_id = request.env["HTTP_X_MESSAGE_ID"]
  attempt_count = request.env["HTTP_X_ATTEMPT_COUNT"]

  puts "Notification received from instance #{instance_id}"
  puts "Message ID: #{message_id}, attempt: #{attempt_count}"

  # Validate the origin before processing
  halt 400, { error: "Missing X-Instance-ID header" }.to_json if instance_id.nil?

  # Process the event
  event = JSON.parse(request.body.read)
  puts "Event: #{event['type']}"

  content_type :json
  { received: true }.to_json
end

Allowlisting in a WAF/firewall: if you use a Web Application Firewall (WAF) or firewall rules, configure it to accept POST requests that carry the X-Instance-ID, X-Message-ID, X-Attempt-Count, and User-Agent headers with the Zapsterapi/ prefix.

Introduction

Concepts

Guides

What are webhooks?

What do webhooks do?

How do webhooks work?

One webhook, many instances

How to do it in practice

Editing and removing: what changes

How to tell the origin apart on the receiver

Best practices

Frequently asked questions

Failure handling and retries

Retry details

Custom HTTP headers

Validation and allowlisting

​What are webhooks?

​What do webhooks do?

​How do webhooks work?

​One webhook, many instances

​Why share a webhook

​How to do it in practice

​Editing and removing: what changes

​How to tell the origin apart on the receiver

​When to share and when to separate

​Best practices

​Frequently asked questions

​Failure handling and retries

​Retry details

​Custom HTTP headers

​Validation and allowlisting

What are webhooks?

What do webhooks do?

How do webhooks work?

One webhook, many instances

Why share a webhook

How to do it in practice

Editing and removing: what changes

How to tell the origin apart on the receiver

When to share and when to separate

Best practices

Frequently asked questions

Failure handling and retries

Retry details

Custom HTTP headers

Validation and allowlisting