Wahio Developers

Get started

1. Add an endpoint

Provide a public HTTP or HTTPS URL that can receive POST requests.

2. Choose events

Select the Wahio events your integration needs and save the secret shown at creation.

3. Verify deliveries

Validate the signature using the raw body, process the event, and return a 2xx response.

Available events

Subscribe each endpoint only to the events it needs.

order.updated

An order is created or its data and status change.

product.updated

A product is created or its catalog information changes.

warehouse-product.updated

Stock or warehouse-specific product information changes.

Electronic billing notifications — deployment pending

The implemented event electronic-billing.updated is awaiting its Service Bus subscription, rollout, activation, and functional validation. It is not part of the available events above yet.

Its data.isValid preserves true, false, or undefined validity. New public emission attempts publish saved accepted, rejected, and unknown-validity results; attempts without a saved outcome do not invent a fiscal status. A synchronous rejection may have no document ID, number, UUID, or files.

This shortened illustrative payload uses camelCase. Customer contact fields, credentials, provider signatures, and the original emission payload are excluded. REST result fields remain snake_case.

{
  "eventId": "order-emission:stable-attempt-id",
  "data": {
    "id": null,
    "accountId": "account-id",
    "orderId": "wahio-order-id",
    "documentType": "invoice",
    "isValid": false,
    "statusCode": "provider-code",
    "statusMessage": "Provider message",
    "errorsMessages": [
      "Provider validation error"
    ],
    "pdfUrl": null,
    "attachedDocumentXmlUrl": null
  }
}

Verify the same Base64 HMAC signature described below, then deduplicate by eventId and account. The event ID stays stable across retries and republication; X-Wahio-Delivery changes for each HTTP attempt. Return 2xx after accepting the work. Duplicate and out-of-order delivery are possible.

Failed or rate-limited fiscal deliveries are returned to Service Bus for redelivery and eventual dead-letter handling. These fiscal failures do not automatically disable the subscription. A receiver that already responded may receive the event again if another receiver fails; a later subscription does not automatically replay past events.

See the electronic billing preparation guide for the emission and reconciliation limits. Notification retries do not issue another invoice or send another invoice email.

Delivery headers

X-Wahio-Event

Event type subscribed to by this endpoint.

X-Wahio-Delivery

Unique identifier for this delivery attempt.

X-Wahio-Signature

Base64 HMAC-SHA256 signature of the exact request body.

X-Wahio-Attempt

Current delivery attempt number.

Payload

Payloads use camelCase. This is a shortened order.updated example.

{
  "data": {
    "id": "order-id",
    "accountId": "account-id"
  },
  "isNew": false,
  "occurredAt": "2026-09-05T01:00:00Z",
  "correlationId": "correlation-id"
}

Verify the signature

Save the webhook secret when the subscription is created—it is shown only once. Compute HMAC-SHA256 over the exact raw request body before parsing JSON, then compare the Base64 result with X-Wahio-Signature using a constant-time comparison.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyWahioSignature(rawBody, signature, secret) {
  const expected = createHmac("sha256", secret).update(rawBody, "utf8").digest();
  const received = Buffer.from(signature, "base64");

  return received.length === expected.length && timingSafeEqual(received, expected);
}

Retries and responses

Return a 2xx response after accepting a delivery. Wahio retries network failures, HTTP 408, HTTP 429, and 5xx responses using the retry policy configured for the subscription. General events can disable the subscription after 10 consecutive delivery failures. The pending fiscal event uses the redelivery policy described above; X-Wahio-Attempt counts attempts within one delivery cycle, not every broker redelivery.

Webhooks