↑↓ selectEnter openEsc close

    1. Elbuz
    2. API v2

    API v2 webhooks: how to get notified about changes

    10 min readUpdated

    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.signed event 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

    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.

    API v2 key card: on behalf of an employee, data changes mode, safety limit and the new key
    1On behalf of
    2Data changes
    3Safety limit: changes per hour
    4Current key
    5Read only
    1. On behalf of — whose permissions and data the key gets. Other employees are visible only to someone with access to the users window.
    2. Data changes — “Ask” (every change waits in Pulse) or “Do it myself”. Only “Management” can switch it.
    3. Safety limit — after this many executed changes per hour the key returns to “Ask” on its own.
    4. The new key is shown once: copy it with the Copy button before closing the window.
    5. 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.

    FieldWhat it sets
    urlhttps only, on the standard port, with no username or password in the URL; all IP addresses of the host must be public
    eventsat least one event from the list below
    batch1 (default): an array of up to 100 events per request; 0: one event per request
    rate_per_minthe maximum number of requests per minute Elbuz will send, from 1 to 600, default 60
    statusactive or off; active also clears the error state
    descriptiona 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

    EventWhen
    contractors.created, contractors.updated, contractors.deleteda 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.signeda 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_overduethe document's payment due date has passed
    pulse.approveda 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

    What Elbuz does with a batch depending on your server's response
    2xxRetry-After presentother code or timeoutnoyesyesnoBatch of up to 100 eventsPOST to your URLServer responseDelivered, next batchSubscription paused for the giventime, attempt not counted6 attempts already?Same batch resent after 1 min, 5min, 30 min, 2 h, 6 hBatch failedThird failed in a row?Subscription in error state, eventsnot queued
    • 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 new webhook-timestamp and signature. 6 attempts in total: immediately, then after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours.
    • A Retry-After header (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 with Retry-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 failed status and are no longer sent. After three such batches in a row, the subscription goes into the error state.

    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

    Common problems
    What you seeWhyWhat to do
    422 “url: https URL required”the URL uses httphttps only (subscription)
    422 “url: private or reserved ip”the host points to an internal addressa public address or a tunnel
    422 “events: unknown event …”the event isn't in the listsee events; you don't subscribe to bulk_* separately
    The signature doesn't matcha transformed body is being signed, or the key wasn't decoded from base64verify the raw body bytes (signature verification)
    The same events arrived twicethe batch was resent after an error or timeoutskip already processed evt_…
    Events stopped arriving, status: errorthree batches in a row weren't deliveredPATCH {"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

    Was this article helpful?

    Missing a feature? Tell us.

    We will add it for free if other users need it too.

    If only you need it, we will agree on it separately.

    Article contents

    Suggest an improvement

    Try Elbuz free