Webhooks

Webhooks allow your applications and integrations to react in real time to what happens in Holded. Instead of querying the API every few minutes to detect changes, you tell Holded a URL and we send you a request the moment an event occurs: an invoice is created, a contact is updated, stock changes, etc.

This article explains how to create a webhook from Holded, what information is available afterward, and how to read and verify the requests we send.

This is a developer-oriented feature. To use webhooks you need an endpoint: a public https:// URL capable of receiving POST requests.

Each delivery is signed, so you can verify it really comes from Holded.

Webhooks are managed from Settings → Developers → Webhooks.

◦ Description — a name to identify the webhook.

◦ Endpoint URL — the public https:// address that will receive the events.

When you create the webhook, Holded shows the signing secret (prefixed with whsec_) only once. Copy it and store it somewhere safe at that moment: you'll need it to verify that requests really come from Holded.

Later you can find it in the webhook's settings, but it will appear partially masked (for example, whsec_••••f776), so it's best to save the full value now. Click Done to finish; the webhook will appear in the list with the status Active.

You can create more than one endpoint (for example, one for billing events and another for inventory) and edit or delete them whenever you want.

☝️ The webhook is configured per Holded account, not at the organization level. If you have several accounts, set up a webhook in each one. They can all point to the same URL: each delivery includes the x-holded-webhook-account-id header so your system can identify which account it came from.

From the list, click a webhook to open its details. Using the toggle next to the name, you can enable or disable it at any time. The detail view has three tabs: Summary, Deliveries, and Settings.

Shows the endpoint's health over the selected period (24h, 7d, or 30d):

This is the webhook's delivery log. You can filter by status (All, Successful, Warnings, Errors), narrow the period (24h/7d/30d), and search by event, ID, or payload. The table shows, for each delivery, its Status, the Event · ID, the Time, and the Latency.

This tab is also the most reliable way to see the exact content your endpoint receives: open any delivery to inspect its actual payload.

Gathers the webhook's data and settings:

Each event is delivered as an HTTP POST request with a JSON body. Holded includes these headers in every request:

Your endpoint must return any 2xx code to confirm delivery. A response other than 2xx (or a timeout) is considered a failed delivery, and Holded retries the delivery up to 5 times.

Respond quickly. Confirm first (return 2xx) and process afterward asynchronously. Heavy work inside the request can cause timeouts and unnecessary retries.

Since a delivery can be retried, design your handler to be idempotent: receiving the same event twice should not duplicate effects. The x-holded-webhook-id header is a reliable deduplication key.

Anyone who knows your endpoint's URL could send it requests, so it's a good idea to verify that each one really comes from Holded before processing it.

Holded signs each request with the signing secret (whsec_…) generated when the endpoint was created. The x-holded-webhook-signature header contains the hexadecimal HMAC-SHA256 digest —preceded by the prefix sha256=— of the string:

<x-holded-webhook-date>.<raw request body>

To verify a request:

The webhook body is a summarized notification of the affected record, not the full object. For example, an invoice payload looks like this:

{

For the full data —document lines, tags, currency, payment status, accounting account, custom fields, etc.— you need to make a GET call to the corresponding resource using the id from the payload. In other words, the webhook tells you what changed and when; the API gives you the detail.

You can check the full structure of each payload, field by field, in the developer reference: www.holded.com/developers/webhooks

Each event's name follows the <area>.<action> pattern and travels in the x-holded-webhook-event header. In the interface, the area appears with its Spanish name and the action as Create / Update / Delete / Approve; the technical event name is in the right-hand column.

It's worth knowing what the webhook system covers and what it doesn't, in order to design your integration well.

Full coverage. All document types (invoices, expenses, estimates, proformas, etc.) emit create, update, delete, and approve as applicable, and contacts emit create, update, and delete. These resources can be kept in sync via webhook after an initial load.

Partial coverage.

No coverage. These resources do not emit webhooks; if you need to sync them, you need periodic polling: warehouses, services, projects, tasks, project time tracking, payments, chart of accounts, general ledger, and recurring invoices.

Payments. There is no dedicated event for payments. Recording a payment triggers an invoice.update or purchase.update, and the payment status doesn't come in the payload: do a GET on the document to find out.