Developers
OpenAPI ↗
Go to the app
Documentation / Integrations
API v1 · Integrations

Integrating webhooks

Securely integrate signed notifications into your ERP or application.

On this page
A closing event instead of repeated status queries

Rebilix sends your server a signed HTTP request as soon as a background job ends, and your server confirms secure reception and then processes the event.

Rebilix jobSigned POST → ERPSave inboxHTTP 200

Five Steps to Integration

  1. Provide a publicly available receiver, for example https://erp.example.com/webhooks/rebilix.
  2. Open: Integration → Orders and Webhooks, select Sandbox or Live and create the receiver. Maximum of five active receivers per environment.
  3. Save the once displayed whsec_…-Secret in the receiver's secret store.
  4. Start a background job and save its job ID to your ERP dataset.
  5. Check the signature and context, save the event permanently and confirm with 2xx. An ERP worker will then retrieve the current result.

For a complete starting point, use the Executable ASP.NET Core Receiver with SQL Server.

What Your Endpoint Needs to Do

RequirementBehaviour
HTTPS · Port 443Public DNS hostname and valid TLS certificate. No IP literals, credentials, query parameters or URL fragments.
POST · application/jsonRead original bytes up to a maximum of 64 KiB; do not deserialize or reformat before the signature check.
Direct responseThe signature authenticates the request, not an ERP browser session.
Quickly confirmRebilix waits at most 15 seconds for the HTTP response to respond to database commit with 2xx.
Publicly availablePrivate / internal destinations are also blocked after DNS resolution. localhost cannot be registered directly as a recipient.

Events and Payload

Receive active recipients of the same environment job.succeeded or job.failedIntermediate automatic retries do not trigger a closing event; new recipients do not receive historical events.

JSON · job.succeeded
{
  "id": "18e7ba7a-7565-4d07-b980-a068d397ff13",
  "type": "job.succeeded",
  "environment": "sandbox",
  "createdAt": "2026-11-01T10:15:00+00:00",
  "version": 1,
  "workspaceId": "11111111-1111-4111-8111-111111111111",
  "jobId": "22222222-2222-4222-8222-222222222222",
  "operation": "validate",
  "state": "succeeded",
  "resultStatus": "valid",
  "documentId": "33333333-3333-4333-8333-333333333333",
  "conversionReviewId": null,
  "errorCode": null
}
FieldSignificance
idEvent UUID. Remains the same for repeat delivery.
Type/Statejob.succeeded / succeeded or job.failed / failed.
Environmentsandbox or live; must fit the receiver configuration.
createdAttTime of the terminal event, not the current delivery attempt.
VersionPayload scheme, currently 1. treat changes consciously.
workspaceIdWorkspace of the order. Compare with the expected client.
jobId / operationOrder and action: generate, parse, validate or conversion review.
resultStatusvalid, invalid, not_checked, ready or blocked; zero for processing errors.
documentIdReference to stored document; otherwise, zero.
conversionReviewIdReference to conversion test; otherwise, zero.
errorcodeTechnical error code at job.failed; zero if successful.
job.succeeded is not an invoice release.

Also included resultStatus: invalid or blocked It may be part of a completed order, and the event does not contain invoice files, customer data or API keys.

JSON · job.failed
{
  "id": "9c692ed6-a07b-49a8-aeb6-10a84c749149",
  "type": "job.failed",
  "environment": "sandbox",
  "createdAt": "2026-11-01T10:18:00+00:00",
  "version": 1,
  "workspaceId": "11111111-1111-4111-8111-111111111111",
  "jobId": "22222222-2222-4222-8222-222222222222",
  "operation": "validate",
  "state": "failed",
  "resultStatus": null,
  "documentId": null,
  "conversionReviewId": null,
  "errorCode": "validation_unavailable"
}

Check the signature against the original bytes

HeadersPurpose
X-Rebilix-Event-IdStable event ID; after checking, compare with payload.id.
X-Rebilix Delivery-IdDelivery for this event/recipient. For correlation only; do not use as a deduplication key.
X-Rebilix timestampUnix seconds, reset for each attempt.
X-Rebilix signaturev1= followed by 64 hex signs.

Calculate HMAC-SHA256 over UTF-8 timestamp + "." + eventId + ".", immediately followed by the unchanged JSON bytes. The HMAC key is the exact UTF-8 string whsec_…Do not decode as Hex or Base64.

C# · Rebilix.Sdk
using Rebilix.Sdk;

// rawBody: begrenzter Request-Body, noch nicht deserialisiert.
bool authentic = RebilixWebhook.Verify(
    rawBody,
    request.Headers["X-Rebilix-Event-Id"].ToString(),
    request.Headers["X-Rebilix-Timestamp"].ToString(),
    request.Headers["X-Rebilix-Signature"].ToString(),
    signingSecret);

if (!authentic)
    return Results.Unauthorized();

// Danach Kontext prüfen und in einer dauerhaften Inbox speichern.
// Vollständiger Receiver: SDK & Beispiele → ZIP herunterladen.

The SDK compares the signature in constant time and allows a maximum of five minutes of time deviation. Keep the server clocks in sync. Only after successful checking does it read JSON and validate Event ID, Workspace, Environment, Version and Event Type.

The delivery ID header does not belong to the signed string; the signed event ID together with the payload is the basis of the processing.

Reliably received and processed

  1. Signature incorrect / time window expired: Reject with 401, do not change ERP data.
  2. Valid new event: Store the original payload and event ID in a persistent inbox. A unique database index prevents parallel duplicates.
  3. Identical already saved event: Return 2xx again, do not perform a second business action.
  4. Database Commit Failed: A 5xx response allows Rebilix to repeat.
  5. After the commit: 200 or 204 respond. A worker reads job status and results with an API key and updates the associated ERP dataset.

ERP change and “processed” marking belong in the same transaction. For external impacts, use your own transactional outbox. A background task without permanent storage is not enough.

Consider order and duplicates

Events can occur multiple times and in a different order, and manually restarted processing can later receive a new closing event, and read the current job status so that an old failure event does not override a new success.

Service and repetition

Response / SituationRebilix behaviour
2xxMark as delivered.
Network error, 408, 429, 5xxRepeat automatically: 30 / 60 / 120 / 240 seconds. Retry after can extend the waiting time up to an hour.
Other HTTP status codesStop automatic repetition. Repeat, if necessary, expressly after error correction.
Connection termination upon receiptResult may be unknown. Double delivery is possible.

Up to five attempts per cycle, a total of a maximum of twenty started delivery attempts; there is no Exactly-once or unlimited delivery guarantee; monitor failed delivery.

Underneath Integration → Orders and Webhooks Payload, trial counter, HTTP status and signature header. API offers GET /webhook-deliveries and GET /webhook-deliveries/{id} with reading rights.

POST /webhook-deliveries/{id}/retry Requires all three rights and JSON {"expectedAttempts":5}, not an idempotency key. Use the currently read counter; an obsolete counter delivers 409. Events that have already been successfully delivered are not re-sent.

Sandbox and local capture

Start with a sandbox receiver and a sandbox job. API keys of the ERP worker and expected environment must also use sandbox.

Operator's configurationImpact
Webhooks:CaptureOnly = trueBy default, payload and signature are logged locally, and no DNS or HTTP call, even to sandbox receivers.
Webhooks:CaptureOnly = falseReal HTTP delivery, also in development and for sandbox events.

Customer-facing receivers cannot change this Rebilix instance setting, and if you have a hosted instance, clarify it with the operator, and for local development, your receiver needs publicly accessible HTTPS access to the local application.

Deliveries already recorded locally will not be sent automatically after switching. Select expressly "Re-delivery" or create a new order. Mail:CaptureOnly is an independent setting for billing emails.

Delivery history recorded with status Local, two attempts and the link details
Under Orders & Webhooks → Delivery History, “Details” shows the individual attempts. “Local Recorded” refers to a recording without HTTP shipping.

Safety and life cycle

The signature secret is not an API key. The receiver uses it only for verification; it retrieves documents with a separate API key with read-rights. Use its own configuration and expected workspace ID per environment and tenant.

For a new destination address or a new signature key, disable the recipient and create a replacement. An HTTP request that is already running may end, and only check both secrets for as long as necessary and retain the inbox deduplication.

The authorization of the creator is checked before deliveries. Loss of role, account suspension or changed security stamp can block the recipient. The Rebilix operator must permanently secure the database and data protection key bundle and share it at several instances.

Conversion confirmation, invoice issuance and e-mail are not triggered by webhooks, and the sample receiver only updates a technical status.

The connection is restored...

New connection attempt in seconds.

The connection could not be restored.
Please try again or reload the page.

Your meeting was paused.

The sitting could not be continued.
Please try again or reload the page.