Skip to main content
A webhook is an HTTP request that Zenedu sends to your endpoint when a specific action happens in your account: an order is placed, a subscriber gets a tag, answers a quiz or writes to the bot. Your system doesn’t need to poll the API to learn about changes: the event arrives on its own, usually within a few seconds.

Ways to receive webhooks

Zenedu sends webhooks in two ways. Both arrive in the same format, are signed the same way and follow the same retry rules.

Quickstart

1

Create an endpoint

Add a public HTTPS endpoint on your server that accepts POST requests with a JSON body and returns a 2xx status.
2

Add a webhook

Open Settings → Workspace → API & Webhooks, click Add in the Webhooks block, enter the URL and select events. Create webhook does the same.
3

Send a test

Click Send test or call Send test webhook. Your endpoint receives the webhook.test event.
4

Verify the signature

Before trusting a request, verify the signature in the Signature header.

Request format

Every webhook is a POST request with a JSON body. The body always has the same shape: service fields and the event object in data.
Objects in data match the API objects: a subscriber is the same as in Get subscriber, an order is the same as in Get order. Event fields, such as tag_id and tag_name, sit next to the subscriber fields.

Headers

Signature

Zenedu signs every webhook. The Signature header contains the HMAC-SHA256 of the raw request body in hex, keyed with the account’s API token. To verify a request, compute the HMAC of the body exactly as received, before parsing the JSON, and compare it with the header:
After you reset the API token, webhooks are signed with the new token.

Best practices

  • Respond quickly. Return 2xx within 3 seconds and do heavy work, such as writing to a CRM, sending emails or calling the API, in a background queue. A request without a response within 3 seconds counts as failed and is retried.
  • Handle duplicates. The same event may arrive more than once. Store the _id of processed deliveries and skip repeats.
  • Don’t rely on order. Each webhook is a separate HTTP request, and because of network delays or a retry, events that happened almost at the same time may arrive in a different order. If order matters, compare timestamp.
  • Subscribe only to the events you need. Extra events load your server for no benefit.

Next steps

Delivery and retries

Retry schedule and automatic disabling

Event catalog

All events and their data

Webhooks in the API

Manage subscriptions through the API