Webhooks

Webhooks let EzPulze notify your system in real time when events happen — like a customer sending a message, reading your reply, or a message failing to deliver. Instead of constantly checking for updates, your system receives an instant HTTP notification the moment something occurs.

📸

Screenshot: Webhooks list page showing table with webhook name, URL, event chips, status toggle, created date, and actions menu

webhooks-list.png

1. Go to Developer Tools → Webhooks from the sidebar
2. Capture the full page showing the webhooks table with several webhooks in different states
Save to: static/img/screenshots/developer-tools/webhooks/webhooks-list.png

Webhooks list

The list page shows all your webhook subscriptions:

Column	Description
Name	Webhook name
Webhook URL	The endpoint URL (truncated — hover to see the full URL)
Events	Event chips showing subscribed events (first 2 shown, then "+X more")
Status	Toggle switch to enable/disable the webhook
Created	Creation date
Actions	Menu with Edit, Test, View Logs, Copy Secret, Delete

Actions

Action	Description
Edit	Change the webhook name, URL, events, or settings
Test	Send a test payload to verify your endpoint is working
View Logs	See delivery history — which events were sent and whether they succeeded
Copy Secret	Copy the secret key for signature verification
Delete	Permanently remove the webhook

Creating a webhook

Click the Add Webhook button to open the creation dialog.

📸

Screenshot: Create Webhook dialog showing name field, URL field, event checkboxes, auto-generated secret key with copy button, and advanced settings with retry count and timeout

create-webhook-dialog.png

1. Click "Add Webhook"
2. Fill in the name and URL
3. Select 2-3 events
4. Show the auto-generated secret key
5. Expand Advanced Settings to show retry and timeout options
6. Capture the full dialog
Save to: static/img/screenshots/developer-tools/webhooks/create-webhook-dialog.png

Webhook fields

Field	Required	Description
Webhook Name	Yes	A descriptive name (e.g., "CRM Sync", "Order Notifications") — max 255 characters
Webhook URL	Yes	Your endpoint URL (must be `https://`) — e.g., `https://myapp.com/webhooks/ezchat`
Events	Yes	Select at least one event to subscribe to (see Events below)

Secret key

When you create a webhook, a secret key is automatically generated. This key is used to verify that incoming webhook requests genuinely come from EzPulze (see Security).

📸

Screenshot: Secret key section showing the masked key with show/hide toggle, copy button, regenerate button, and warning message

secret-key-section.png

1. In the Create Webhook dialog, capture the secret key section showing the key, copy button, and regenerate button
Save to: static/img/screenshots/developer-tools/webhooks/secret-key-section.png

Save your secret key

The secret key is only shown once when creating the webhook. Copy it and store it securely. You'll need it to verify webhook signatures.

Advanced settings

Expand the Advanced Settings panel for additional configuration:

Setting	Description	Default	Range
Retry Count	Number of retry attempts if delivery fails	3	0–5
Timeout	How long to wait for your server to respond (in milliseconds)	5,000 ms	1,000–30,000 ms
Active	Whether the webhook is enabled	On	—

Events

You can subscribe to one or more of these events:

Event	Description	When it fires
Message Received	A customer sent a message to your WhatsApp number	Instantly when a new message arrives
Message Sent	A message was successfully sent from EzPulze	After EzPulze sends a message (broadcast, chatbot, or manual)
Message Delivered	A message was delivered to the customer's phone	When WhatsApp confirms delivery (double check marks)
Message Read	A customer opened and read your message	When WhatsApp confirms the message was read (blue check marks)
Message Failed	A message failed to send	When WhatsApp returns an error for a message

Event payload

Every webhook delivery sends a JSON payload with this structure:

{
  "event": "message.received",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "data": {
    "messageId": "wamid.abc123...",
    "from": "919876543210",
    "to": "919876543211",
    "contactName": "John Doe",
    "type": "text",
    "text": "Hi, I want to know about your services",
    "timestamp": "2026-01-15T10:30:00.000Z"
  }
}

The data object varies by event type — for example, Message Sent includes templateName and campaignName, while Message Failed includes errors with error details.

Testing a webhook

Click Test from the actions menu to send a sample payload to your endpoint. This helps verify that:

Your URL is reachable
Your server processes the payload correctly
Signature verification is working

The test sends a sample message.received event payload.

Delivery logs

Click View Logs to see the delivery history for a webhook.

📸

Screenshot: Delivery Logs dialog showing a split view with log entries on the left (timestamp, status, event, HTTP status) and log details on the right with Request Payload, Response, and Details tabs

delivery-logs-dialog.png

1. Click "View Logs" on a webhook that has been active
2. Select a log entry from the left panel
3. Show the Request Payload tab on the right
4. Capture the full split-view dialog
Save to: static/img/screenshots/developer-tools/webhooks/delivery-logs-dialog.png

Log list (left panel)

Each log entry shows:

Element	Description
Timestamp	When the delivery was attempted
Status badge	Success (green), Failed (red), Pending (yellow), Retrying (blue)
Event type	Which event triggered the delivery
HTTP status	Response code from your server (e.g., 200, 500)
Error preview	First 50 characters of the error message (if failed)

Click a log entry to see its details on the right panel.

Log details (right panel)

Three tabs show the full details:

Tab	Content
Request Payload	The complete JSON payload that was sent to your endpoint (with copy button)
Response	Your server's response body
Details	Delivery ID, status, HTTP status, retry count, timestamps, and full error message

Logs load 50 at a time — click Load More to see older entries.

Security & signature verification

Every webhook request includes a signature in the X-Webhook-Signature header. This lets you verify that the request genuinely came from EzPulze and wasn't tampered with.

HTTP headers

Each webhook request includes these headers:

Header	Description
`X-Webhook-Signature`	HMAC-SHA256 signature of the request body
`X-Webhook-Event`	Event type (e.g., `message.received`)
`X-Webhook-Id`	Unique delivery ID
`Content-Type`	`application/json`

How to verify the signature

Extract the X-Webhook-Signature header from the request
Compute the HMAC-SHA256 hash of the raw request body using your secret key
Compare the computed hash with the header value
If they match, the request is authentic

Example: Node.js

const crypto = require('crypto');

function verifyWebhookSignature(body, signature, secret) {
  const computed = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return computed === signature;
}

// In your Express route handler:
app.post('/webhooks/ezchat', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    'your-secret-key'
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process the webhook...
  res.status(200).send('OK');
});

Example: Python

import hmac
import hashlib

def verify_signature(body, signature, secret):
    computed = hmac.new(
        secret.encode(),
        body.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(computed, signature)

Example: PHP

function verifySignature($body, $signature, $secret) {
    $computed = hash_hmac('sha256', $body, $secret);
    return hash_equals($computed, $signature);
}

Webhook documentation page

EzPulze includes a built-in Webhook Documentation page with comprehensive integration guides.

📸

Screenshot: Webhook Documentation page showing navigation sidebar with sections for Introduction, Events, Payload Format, Security, and n8n Integration

webhook-docs-page.png

1. Navigate to the Webhook Documentation page
2. Capture the page showing the navigation sidebar and content area with code examples
Save to: static/img/screenshots/developer-tools/webhooks/webhook-docs-page.png

Sections

Section	Content
Introduction	What webhooks are, how they work
Available Events	All 5 event types with descriptions
Payload Format	JSON structure with field descriptions
HTTP Headers	Signature, event, and ID headers
Security	Signature verification with code examples in Node.js, Python, and PHP
Best Practices	Tips for reliable webhook handling
n8n Integration	Step-by-step guide to connect EzPulze with n8n (if available)

n8n integration

If you use n8n for workflow automation, the documentation page includes a dedicated guide for connecting EzPulze webhooks to n8n workflows.

Setup steps

Create a Webhook node in n8n
Copy the n8n webhook URL
Create a webhook subscription in EzPulze with that URL
Select the events you want to receive
Use the n8n workflow to process incoming events

Example use cases with n8n

Auto-respond to new messages — Trigger an n8n workflow when a customer messages, then send an auto-reply
CRM sync — When a message is received, create or update a contact in your CRM
Notifications — Send a Slack or email notification when a message fails to deliver
Analytics — Log message events to Google Sheets or a database

Retry behavior

When a webhook delivery fails (your server returns an error or times out):

The system logs the failure with the error details
The retry count setting determines how many additional attempts are made (0–5)
Failed deliveries are logged with the error message and HTTP status code

tip

Set your server to return a 200 status code quickly. Process the webhook payload asynchronously if it requires heavy computation. This prevents timeouts.

Tips

Always verify signatures — This prevents unauthorized systems from sending fake webhooks to your endpoint
Respond quickly — Return a 200 status within the timeout period, then process the data asynchronously
Monitor delivery logs — Check logs regularly to catch any delivery failures early
Use HTTPS — Webhook URLs must use HTTPS to ensure data is encrypted in transit
Start with the Test button — Before relying on a webhook in production, test it to make sure your endpoint works
Subscribe to only the events you need — This reduces unnecessary traffic to your server

Webhooks list​

Actions​

Creating a webhook​

Webhook fields​

Secret key​

Advanced settings​

Events​

Event payload​

Testing a webhook​

Delivery logs​

Log list (left panel)​

Log details (right panel)​

Security & signature verification​

HTTP headers​

How to verify the signature​

Example: Node.js​

Example: Python​

Example: PHP​

Webhook documentation page​

Sections​

n8n integration​

Setup steps​

Example use cases with n8n​

Retry behavior​

Tips​