Elbuz sends a notification to your server's URL whenever customers or documents change, or a request is approved in “Pulse”. No need to poll the API every minute for “what's new”.
When you need this:
- New customers must reach your CRM: the event arrives within a minute of creation.
- Posted orders must go to the warehouse: a
documents.signedevent per document. - Your server can't handle the load: events arrive in batches of up to 100, with a per-minute request limit.
- Your server was down: the batch is resent, up to six attempts.
Where to start: create a subscription with an API request, using the key you'll read records with.
What webhooks can do
- Notify you about customers and documents: creation, changes, moving to Trash, posting, overdue payment, an approved “Pulse” request.
- Roll a bulk action into one event: instead of a hundred events you get one with a list of ids.
- Merge several changes to one record: you read the final state.
- Sign every request following the Standard Webhooks specification.
- Retry delivery and pause when your server asks.
How to subscribe
You create a subscription with an API request, using the key you'll later read records with. Keys are issued in the “API & access tokens” window (details: API v2: keys); for subscriptions, the key must have “Read only” cleared.
1
On behalf of2
Data changes3
Safety limit: changes per hour4
Current key5
Read only- On behalf of — whose permissions and data the key gets. Other employees are visible only to someone with access to the users window.
- Data changes — “Ask” (every change waits in Pulse) or “Do it myself”. Only “Management” can switch it.
- Safety limit — after this many executed changes per hour the key returns to “Ask” on its own.
- The new key is shown once: copy it with the Copy button before closing the window.
- Read only — on for a new key; clear it if the key needs to change something.
curl -s -X POST "https://<your-domain>/api/v2/webhooks" \
-H "Authorization: Bearer elbz_…" -H "Content-Type: application/json" \
-H "Idempotency-Key: wh-crm-sync-1" \
-d '{"url":"https://example.com/elbuz-hook",
"events":["contractors.created","contractors.deleted","documents.updated"],
"description":"CRM sync","batch":1,"rate_per_min":60}'
The 201 response (demo account, 14.10.2026):
{"data":{"secret":"whsec_biVB0fz/Dm5U0yfY59idgl5lpaXngK7Vey3ngKCZzpY=",
"webhook_id":9,"url":"https://example.com/elbuz-hook",
"events":["contractors.created","contractors.deleted","documents.updated"],
"status":"active","description":"CRM sync","batch":1,"rate_per_min":60, …}}
The whsec_… secret is shown only in this response. It's stored encrypted, GET /api/v2/webhooks/9 doesn't return it, and repeating the request with the same Idempotency-Key returns “*** shown once ***”. Lost the secret? Delete the subscription and create a new one.
| Field | What it sets |
|---|---|
url | https only, on the standard port, with no username or password in the URL; all IP addresses of the host must be public |
events | at least one event from the list below |
batch | 1 (default): an array of up to 100 events per request; 0: one event per request |
rate_per_min | the maximum number of requests per minute Elbuz will send, from 1 to 600, default 60 |
status | active or off; active also clears the error state |
description | a note, up to 255 characters |
To change a subscription, use PATCH /api/v2/webhooks/{id}; to delete it, DELETE (response 204, the delivery log is kept). Only the key that created a subscription can see and change it: another key of the same account gets 404. Subscriptions don't create requests in “Pulse”, in any key mode.
The URL is checked on creation, on change and before every send. Rejections come with an explanation: url: https URL required, url: private or reserved ip, url: port not allowed. Elbuz doesn't follow redirects (3xx): such a response counts as a delivery error.
Which events you can subscribe to
| Event | When |
|---|---|
contractors.created, contractors.updated, contractors.deleted | a customer or supplier was created, changed or moved to Trash: in a window, by import, via the old API or API v2 |
documents.created, documents.updated, documents.deleted, documents.signed | a document (order, invoice, deal) was created, changed, moved to Trash or posted. documents.updated also arrives when an order was changed by an import: the tunnel, marketplaces that update orders (list), POST /orders/sync. If the order came in unchanged, there's no event |
documents.payment_overdue | the document's payment due date has passed |
pulse.approved | a request was approved in “Pulse” |
You can only subscribe to events for resources the key owner can see: with no access to the customers window, contractors.* returns 422 “events: no access to contractors”. There are no product events yet: fetch catalog changes with the list GET /api/v2/products?filter[updated_since]=….
What the request contains
With batch=1 the body is an array of up to 100 events; with batch=0, a single such object. A sample request (the ids and signature are placeholders):
POST /elbuz-hook
Content-Type: application/json
User-Agent: Elbuz-Webhooks/1
webhook-id: msg_3db9ec1f3f81b1fa1bf46510
webhook-timestamp: 1791974700
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
[{"id":"evt_96788537a68c0722d7b6fa82","type":"contractors.updated","timestamp":"2026-10-14T10:45:00Z",
"data":{"id":19277,"resource":"contractors"}},
{"id":"evt_1f0c2a9e44d7b8a5c3e6f701","type":"documents.signed","timestamp":"2026-10-14T10:45:02Z",
"data":{"id":5120,"resource":"documents"}}]
An event carries only the record id. The data itself isn't in the body: read the record with GET /api/v2/{resource}/{id} using your key. This way you always get the current state and only the fields your key is allowed to see. timestamp is the event time in UTC.
A bulk action is one event
If one action changed more than one record of the same kind (you deleted a grid selection, changed a field in a hundred documents, an import ran), you get one {resource}.bulk_{action} event instead of a hundred:
{"id":"evt_…","type":"contractors.bulk_deleted","timestamp":"2026-10-14T10:44:58Z",
"data":{"resource":"contractors","action":"deleted","count":50,
"ids":[19227,19228,19229, …],"truncated":false,"operation_id":"op_3514f5e4c0df634e"}}
ids holds up to 1000 ids; if there are more records, truncated: true, and for created and changed records there's also list_url: a list of changes from the last hour that you read to the end with a cursor.
You don't subscribe to bulk_* separately: a subscription to contractors.deleted also receives contractors.bulk_deleted. The exception is documents.payment_overdue: always a separate event per document, and no more than once every 30 days for the same document.
Several changes to one record
An updated event waits 60 seconds before it's sent. If the same record changes again during that time, no new event is added: you get one and read the final state. created, deleted and signed events don't wait.
When it arrives
Nothing is sent at the moment of the action: events are collected until the action (request, import) ends, then go into the subscription queue, and a background task sends them. Expect a delay of up to a minute, plus the 60-second merge window for updated.
Batches go one at a time: a subscription never has two requests in flight at once. But because of the 60-second merge window, an updated event may arrive later than an event that happened after it, for example after deleted for the same record. Rely on the state from GET, not on the order of events.
How to verify the signature
Format: Standard Webhooks. Signature: HMAC-SHA256 of the string webhook-id + "." + webhook-timestamp + "." + raw body; key: the decoded base64 part of the secret after whsec_; result: base64 with the v1, prefix. The body is signed byte for byte: don't parse the before verifying. Reject requests whose webhook-timestamp is more than 5 minutes off the current time.
PHP
$secret = 'whsec_…';
$id = $_SERVER['HTTP_WEBHOOK_ID'];
$ts = $_SERVER['HTTP_WEBHOOK_TIMESTAMP'];
$body = file_get_contents('php://input');
$key = base64_decode(substr($secret, 6));
$expected = 'v1,' . base64_encode(hash_hmac('sha256', $id . '.' . $ts . '.' . $body, $key, true));
$valid = abs(time() - (int)$ts) <= 300
&& in_array(true, array_map(fn($s) => hash_equals($expected, $s),
explode(' ', $_SERVER['HTTP_WEBHOOK_SIGNATURE'])), true);
if (!$valid) { http_response_code(401); exit; }
Node.js (Express)
const crypto = require('crypto');
app.post('/elbuz-hook', express.raw({ type: 'application/json' }), (req, res) => {
const key = Buffer.from(process.env.ELBUZ_WHSEC.slice(6), 'base64');
const id = req.get('webhook-id'), ts = req.get('webhook-timestamp');
const expected = 'v1,' + crypto.createHmac('sha256', key)
.update(id + '.' + ts + '.' + req.body.toString('utf8')).digest('base64');
const fresh = Math.abs(Date.now() / 1000 - Number(ts)) <= 300;
const ok = req.get('webhook-signature').split(' ').some(s =>
s.length === expected.length && crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected)));
if (!fresh || !ok) return res.sendStatus(401);
res.sendStatus(200);
});
Python
import base64, hashlib, hmac, time
def valid(secret, headers, raw_body: bytes) -> bool:
key = base64.b64decode(secret[6:])
msg = f"{headers['webhook-id']}.{headers['webhook-timestamp']}.".encode() + raw_body
expected = "v1," + base64.b64encode(hmac.new(key, msg, hashlib.sha256).digest()).decode()
fresh = abs(time.time() - int(headers['webhook-timestamp'])) <= 300
return fresh and any(hmac.compare_digest(expected, s) for s in headers['webhook-signature'].split())
All three examples were tested against a signature computed the same way Elbuz computes it.
How to respond and how Elbuz retries
- Start or end
- Action or result
- Decision: the path depends on the answer
- Any 2xx code: the batch is delivered. Respond quickly: Elbuz waits 15 seconds (5 for the connection). Move heavy processing to your own queue.
- Any other code, a timeout, a dropped connection: the batch is resent in full: the same
webhook-id, the same body, a newwebhook-timestampand signature. 6 attempts in total: immediately, then after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours. - A
Retry-Afterheader (usually with 429): the subscription pauses for the given number of seconds, up to a day. Such a response doesn't count as an attempt: while you respond withRetry-After, the batch is resent with no limit; the six attempts count only errors without this header. - While a batch waits for a retry, the subscription's new events wait behind it, so the order is kept.
- Once six attempts are used up, the batch and its events get the
failedstatus and are no longer sent. After three such batches in a row, the subscription goes into theerrorstate.
A subscription in the off or error state doesn't queue events: changes made while it was inactive won't arrive. After you reactivate it (PATCH {"status":"active"}), catch up on what you missed with the ?filter[updated_since]= list, starting from the last successful delivery.
Processing without duplicates
A batch can arrive twice: your server processed it, but the response didn't get through. Store the id of each event (evt_…) and skip those already processed. Use the event id, not webhook-id: webhook-id belongs to the batch.
Delivery log
GET /api/v2/webhook_deliveries?filter[webhook_id]=9 returns the subscription's last 200 batches, newest first:
{"delivery_id":51,"msg_id":"msg_3db9ec1f3f81b1fa1bf46510","types":"contractors.updated",
"events_count":"50","status":"sent","attempts":"1","response_code":"200","error":"",
"next_try":null,"date_try":"…","date_sent":"…"}
status: queued: being prepared; retry: waiting to retry until next_try; sent: delivered; failed: attempts used up. The log and events are kept for 30 days.
Scenarios
New customers into your CRM
Subscribe to contractors.created. For each event, call GET /api/v2/contractors/{id}; for contractors.bulk_created after an import, call GET /api/v2/contractors?filter[contractor_id][gte]=… or go through ids.
Posted orders to the warehouse
Subscribe to documents.signed, with batch=0 if your warehouse accepts one order at a time. Get the lines with GET /api/v2/document_items?filter[document_id]={id}.
A slow receiver
Your server handles 10 requests per minute: rate_per_min=10 and batch=1 give up to 1000 events per minute in batches of 100. At peak load, respond with 429 and Retry-After: 60.
What to do when events don't arrive
| What you see | Why | What to do |
|---|---|---|
| 422 “url: https URL required” | the URL uses http | https only (subscription) |
| 422 “url: private or reserved ip” | the host points to an internal address | a public address or a tunnel |
| 422 “events: unknown event …” | the event isn't in the list | see events; you don't subscribe to bulk_* separately |
| The signature doesn't match | a transformed body is being signed, or the key wasn't decoded from base64 | verify the raw body bytes (signature verification) |
| The same events arrived twice | the batch was resent after an error or timeout | skip already processed evt_… |
Events stopped arriving, status: error | three batches in a row weren't delivered | PATCH {"status":"active"} and catch up on what you missed |
FAQ
Where do I get the webhook signing secret?
Only in the response to creating the subscription, in the secret field (whsec_…). It can't be shown later; if you lose it, create a new subscription.
Why did I get one event instead of a hundred?
A bulk action (deleting a selection, bulk editing, an import) produces one {resource}.bulk_{action} event with count and up to 1000 ids.
How many times does Elbuz retry delivery?
Six attempts: immediately, then after 1 min, 5 min, 30 min, 2 h and 6 h. A response with Retry-After pauses delivery for up to a day and doesn't count as an attempt.
Why is there no customer data in the event?
An event contains only the id. You read records with GET /api/v2/{resource}/{id}, getting the current state within your key's permissions.
Are there webhooks for product changes?
No. For the catalog, use the list GET /api/v2/products?filter[updated_since]=… and page through it with a cursor.
How do I test webhooks on my own computer?
Only through a public https tunnel: Elbuz rejects http URLs and internal addresses (URL requirements).
Where to find it and who has access
There are no subscriptions in the app's windows: you create and change them with requests.
- Key
- an API v2 key without “Read only” (how to issue one)
- Access rights
- events only about resources the key owner can see
- Prepare
- an
https://URL on your server, reachable from the internet
Related topics
- If you need to read a record from an event: API v2: key, lists, changes.
- If you need to fetch catalog changes regularly: lists filtered by change date.
- If Claude or ChatGPT should analyze the data: connect an AI assistant via MCP.
