Webhooks
On this page
Purpose
Billyou sends HTTPS POST requests to an endpoint you register when an invoice, customer, e-Factura, e-Transport, expense, or partner-account event happens.
Manage endpoints with the API (/webhooks/endpoints, under the API base URL) or in the Developer Portal. Creating an endpoint returns the signing secret. You can read it again with GET /webhooks/endpoints/{id}/secret.
Register an endpoint
POST /api/webhooks/endpoints
X-API-Key: bk_user_<key>
Content-Type: application/json
{
"url": "https://example.com/webhooks/billyou",
"description": "Production invoices",
"events": ["invoice.issued", "invoice.paid"]
}
url must be HTTPS. events needs at least one type. You can list, update, disable, delete, and send a test event (POST /api/webhooks/endpoints/:id/test). Delivery history is GET /api/webhooks/deliveries. Event names are also listed by GET /api/webhooks/event-types.
Field-level schemas for endpoint management are in the webhook reference. The delivery contract below is the one implemented in release 2.3.3.
Event types
Release 2.3.3 documents these 17 types:
| Event | When |
|---|---|
invoice.issued | The invoice is finalized and sent |
invoice.paid | Recorded payments cover the invoice total |
invoice.canceled | The invoice is cancelled |
invoice.storno.issued | A storno document is issued |
invoice.efactura_sent | The invoice is submitted to ANAF |
invoice.efactura_accepted | ANAF accepts the invoice |
invoice.efactura_rejected | ANAF rejects the invoice |
invoice.efactura_received | An inbound e-Factura is received |
customer.created | A client is created |
customer.updated | A client is updated |
customer.deleted | A client is deleted |
expense.created_from_efactura | An expense is created from an inbound e-Factura |
etransport.declaration.processed | ANAF accepts a declaration and a UIT code is available |
etransport.declaration.rejected | ANAF rejects a declaration |
account.provisioned | A partner creates a trial account |
account.activated | That end-customer finishes registration |
account.subscribed | That end-customer starts a paid plan |
account.* events go to the partner's endpoints. Inside data.object, organizationId is the child organization and partnerOrgId is the partner. The partner reference has those fields.
Delivery body
Every delivery is JSON with this shape:
{
"id": "evt_...",
"type": "invoice.issued",
"api_version": "2026-03-01",
"created": "2026-01-15T10:00:00.000Z",
"data": {
"object": {}
}
}
api_version is always 2026-03-01, including when the API call that produced the event used Billyou-Version: 2026-08-01. data.object is the event resource. id starts with evt_ and changes on every attempt, including retries of the same delivery. Dedupe on the Billyou-Delivery header, which stays the same across attempts. Deliveries do not include an Idempotency-Key header.
Headers on a delivery
| Header | Value |
|---|---|
Content-Type | application/json |
Billyou-Signature | t=<unix seconds>,v1=<hmac-sha256 hex of timestamp + "." + raw body> |
Billyou-Event | Event name |
Billyou-Delivery | Stable delivery id. Use it to ignore duplicates |
User-Agent | Billyou-Webhooks/1.0 |
Verify the signature
- Read the raw body before parsing JSON.
- Split
Billyou-Signatureon commas, then split each part on the first=, and readtandv1. - Compute HMAC-SHA256 over the string
t + "." + raw_body, using the endpoint secret, and hex-encode it. - Compare with
v1using a timing-safe compare.
Success and failure
A delivery succeeds only when the endpoint returns a status from 200 through 299.
A delivery fails when any of these happen:
- the status is outside 200–299
- the endpoint responds with a redirect (Billyou does not follow it)
- the endpoint does not respond within 30 seconds
- the connection fails with a network error
Retries
A delivery is sent at most 5 times, including the first send.
| Attempt | When it is sent |
|---|---|
| 1 | Immediately |
| 2 | 5 minutes after attempt 1 fails |
| 3 | 30 minutes after attempt 2 fails |
| 4 | 2 hours after attempt 3 fails |
| 5 | 24 hours after attempt 4 fails |
After attempt 5 the delivery is permanently_failed. The waits add up to about 26 hours 35 minutes. The retry worker polls every 60 seconds and does not add jitter, so each wait can start up to about one minute late.
The manual retry control in the dashboard does not send a new delivery.
Disabled endpoints
An endpoint is disabled automatically, with reason consecutive_failures, after 10 consecutive failed HTTP attempts across deliveries. One successful delivery resets that counter.