Webhooks: Real-Time Event Notifications in Convo

Webhooks are HTTP callbacks that Convo uses to push real-time event notifications to your server. Instead of polling the API to find out whether a message was delivered or a new contact was created, you register a publicly accessible endpoint and Convo sends an HTTP POST request to that URL the moment the event occurs. This makes webhooks the most efficient way to build reactive, event-driven integrations on top of the Convo platform.

Webhook subscriptions can be created and managed via the Convo dashboard (under Integrations → Custom Apps) or programmatically through the Webhooks API endpoints.

Webhook Topics

A topic identifies the type of event that triggers a webhook delivery. When you register a webhook, you subscribe to one or more topics. Convo only sends notifications for the topics you have subscribed to.

Topic	Triggered When
`contact.created`	A new Contact is created in your Project (via API, import, or first inbound message).
`message.sent`	A message has been successfully submitted to WhatsApp from your Project.
`message.delivered`	A message has been delivered to the recipient’s device (double grey tick).
`message.read`	A message has been read by the recipient (double blue tick).

Additional event topics may be available for your plan. Check the Integrations section of your dashboard for the full list of topics supported on your account.

Webhook Object Fields

When you create a webhook, Convo stores a webhook subscription object with the following fields:

Field	Type	Description
`id`	string	Unique identifier for this webhook subscription.
`app_id`	string	ID of the Custom App this webhook is associated with.
`project_id`	string	The Project that will trigger events for this webhook.
`topics`	array of strings	The list of event topics this webhook is subscribed to.
`webhook_url`	string	Your publicly accessible HTTPS endpoint that receives POST requests.
`shared_secret`	string	A secret token used to sign webhook payloads so you can verify their authenticity.
`created_at`	ISO 8601 datetime	Timestamp when this webhook subscription was created.

Securing Webhooks

Because your webhook endpoint is publicly accessible, you need to verify that incoming requests genuinely originate from Convo and have not been tampered with in transit. Convo uses the shared_secret you configure to sign every webhook payload. How to verify the signature:

Read the signature header

Convo includes a signature in the x-convo-signature HTTP header of every webhook request.

Compute the expected signature

Use your shared_secret and the raw request body to compute an HMAC digest (SHA-256) and compare it against the value in the header.

Reject mismatched requests

If the signatures do not match, discard the request — it was not sent by Convo or the payload was modified in transit. Return a 401 Unauthorized response.

Respond with 200 OK

If the signature is valid, process the event and return 200 OK promptly. Convo considers any non-2xx response a delivery failure and will retry.

Here is a minimal webhook handler in Node.js / Express that logs the incoming event:

const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-convo-signature'];

  // Verify signature using your shared_secret
  const expectedSignature = crypto
    .createHmac('sha256', process.env.CONVO_SHARED_SECRET)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (signature !== expectedSignature) {
    console.warn('Webhook signature mismatch — request rejected.');
    return res.sendStatus(401);
  }

  // Signature verified — process the event
  const payload = req.body;
  console.log('Webhook event:', payload.topic, payload);

  // Always respond quickly so Convo does not retry
  res.sendStatus(200);
});

app.listen(3000, () => console.log('Webhook listener running on port 3000'));

Always store your shared_secret in an environment variable, never hard-code it in your source code. Rotate the secret immediately if you suspect it has been exposed.

Custom Apps

Webhooks in Convo are scoped to a Custom App. A Custom App is a named integration you create in the dashboard that groups your webhook subscriptions and API credentials together.

Navigate to Integrations → Custom Apps in the Convo dashboard to create a new Custom App.
Each Custom App receives a unique app_id.
You can create multiple Custom Apps per Project — for example, one for your CRM integration and another for your order management system — each with its own webhook URL and shared secret.
Deleting a Custom App removes all associated webhook subscriptions.

Webhook Lifecycle

Action	How
Create	Via the Convo dashboard (Integrations → Custom Apps → Add Webhook) or the Partner API.
List	Retrieve all webhook subscriptions for a Custom App via the API or view them in the dashboard.
Get details	Fetch a single webhook subscription by its `id` to inspect topics, URL, and metadata.
Delete	Remove a webhook subscription via the dashboard or API. Deletion is immediate — no further events will be delivered to that URL.

Convo retries failed webhook deliveries (non-2xx responses or timeouts) with exponential back-off. Ensure your endpoint responds within the timeout window and handles duplicate deliveries idempotently, as retries may result in the same event being posted more than once.

Get Started

Core Concepts

Guides

Webhooks: Real-Time Event Notifications in Convo

Webhook Topics

Webhook Object Fields

Securing Webhooks

Custom Apps

Webhook Lifecycle

​Webhook Topics

​Webhook Object Fields

​Securing Webhooks

​Custom Apps

​Webhook Lifecycle

Webhook Topics

Webhook Object Fields

Securing Webhooks

Custom Apps

Webhook Lifecycle