Webhooks

Webhooks (referred to as callbacks in the API schema) allow you to receive real-time HTTP POST notifications when events occur within your Billogram account.

Terminology

In the Billogram openapi.yaml and web settings, the term callback is used for historical reasons. These fields represent your webhook configuration. A future API version may rename these to webhook_*, but their functionality remains identical.

Configuration

1. Account-Level Callback (Recommended)

You can set a global callback URL and signing key in your business account settings via the web interface.

2. Per-Billogram Callbacks (Override)

For specific routing needs, you can define a callbacks object when creating a billogram.

Field	Description
`url`	HTTPS required. The endpoint Billogram will POST to.
`sign_key`	The secret key used to generate the `Billogram-Signature`.
`custom`	A string echoed back in the `BillogramEvent` envelope.

Security & Verification

HTTPS Requirement

Billogram requires your callback URL to use HTTPS. The server will reject unencrypted endpoints.

Signature Verification (Recommended)

When a sign_key is configured, Billogram adds two headers to every request:

Billogram-Request-Timestamp
Billogram-Signature

Verification Steps:

Read the Billogram-Request-Timestamp header and the raw request body exactly as received.
Create the base string: timestamp + ":" + raw_body Example: 1550155518.141119:{"callback_id":"...","callback_type":"..."...}
Compute HMAC SHA-256 over that base string using your sign_key.
Perform a timing-safe comparison of your computed signature against the Billogram-Signature header.

Important: Use the raw body bytes (before JSON parsing) when computing the signature.

Webhook Types & Envelopes

Every request includes a callback_type field to help you route the payload.

`callback_type`	Description	Market/Status
`BillogramEvent`	Lifecycle events (Payment, Sent, Overdue, etc.)	Global
`RecipientUpdated`	Customer verifies email or changes recurring payment.	Global
`PaymentRecalled`	Negative allocation due to recalled payments.	Global
`EinvoiceRegistrationCreated`	Successful E-invoice registration.	Global
`EinvoiceRegistrationDeleted`	E-invoice registration removed.	Global
`BillingTab`	Billing Tab processing events.	Global
`EinvoiceRegistrationIdentificationMismatch`	Failed registration due to ID mismatch.	Finland Only
`EinvoiceRegistrationRecipientNotFound`	Failed registration; customer number mismatch.	Finland Only
`EfakturaRegistration`	Legacy Swedish internet bank registrations.	Deprecated

BillogramEvent details

Envelope shape (example)

{
  "callback_id": "unique-id-for-this-delivery",
  "callback_timestamp": "2026-02-20T10:15:30Z",
  "callback_type": "BillogramEvent",
  "custom": "optional-routing-value",
  "billogram": { },
  "event": {
    "type": "Payment",
    "created_at": "2026-02-20 10:15:29",
    "data": { }
  },
  "signature": "deprecated-legacy-field"
}

Discriminator: `event.type`

For callback_type = BillogramEvent, the concrete event schema is determined by event.type.

Common examples:

BillogramCreated
BillogramSent
DeliveryFailed
Resent
ReminderSent
Payment
BillogramEnded
Credit

Do not assume this list is complete. The OpenAPI specification defines the full set of supported event.type values via a discriminator mapping.

Best Practices

1. Acknowledge with 200 OK

Your server must return an HTTP 200 OK status. Any other status (or a timeout) will trigger Billogram's retry logic. Failed webhooks eventually trigger a detailed error email to your account's contact address.

2. Handle Out-of-Order Delivery

Webhooks are not guaranteed to arrive in order.

Primary Sort: Use the event.created_at timestamp (for BillogramEvent).
Secondary Sort: Use the callback_timestamp.

3. Implement Idempotency

Use the callback_id provided in the JSON envelope to deduplicate requests and prevent processing the same event twice.

4. Forward Compatibility

Billogram may add new event types or fields. Your implementation should gracefully ignore unknown fields and log unknown callback_type or event.type values while still returning a 200 OK.

5. Use the `custom` Field for Internal Correlation

The custom value is echoed back in every BillogramEvent webhook for that billogram. This makes it useful for storing internal identifiers—such as your internal invoice number, order ID, or correlation ID—that are not included in the standard webhook data. By setting custom when creating a billogram, you can reliably correlate all lifecycle events (Payment, Sent, Overdue, etc.) with your own records without additional lookups.

Requests & Responses

Workflows