BillyouHelp

↑↓ select · ↵ open · Esc close

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:

EventWhen
invoice.issuedThe invoice is finalized and sent
invoice.paidRecorded payments cover the invoice total
invoice.canceledThe invoice is cancelled
invoice.storno.issuedA storno document is issued
invoice.efactura_sentThe invoice is submitted to ANAF
invoice.efactura_acceptedANAF accepts the invoice
invoice.efactura_rejectedANAF rejects the invoice
invoice.efactura_receivedAn inbound e-Factura is received
customer.createdA client is created
customer.updatedA client is updated
customer.deletedA client is deleted
expense.created_from_efacturaAn expense is created from an inbound e-Factura
etransport.declaration.processedANAF accepts a declaration and a UIT code is available
etransport.declaration.rejectedANAF rejects a declaration
account.provisionedA partner creates a trial account
account.activatedThat end-customer finishes registration
account.subscribedThat 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

HeaderValue
Content-Typeapplication/json
Billyou-Signaturet=<unix seconds>,v1=<hmac-sha256 hex of timestamp + "." + raw body>
Billyou-EventEvent name
Billyou-DeliveryStable delivery id. Use it to ignore duplicates
User-AgentBillyou-Webhooks/1.0

Verify the signature

  1. Read the raw body before parsing JSON.
  2. Split Billyou-Signature on commas, then split each part on the first =, and read t and v1.
  3. Compute HMAC-SHA256 over the string t + "." + raw_body, using the endpoint secret, and hex-encode it.
  4. Compare with v1 using 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.

AttemptWhen it is sent
1Immediately
25 minutes after attempt 1 fails
330 minutes after attempt 2 fails
42 hours after attempt 3 fails
524 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.