Webhooks

Receive HTTPS signed notifications every time an operation or a flow changes state. Your system stays in sync in real time without polling.

A few examples of what you'll receive: an operation being opened, a successful payment, a rejection, a flow expiry, or cancellations performed via the API. Every webhook is signed with HMAC-SHA256 for authenticity and integrity, using webhooks instead of polling cuts latency, traffic and integration complexity.

1 Register your endpoint → get the webhookSecret

Provide Zertiban with:

• Your businessUuid
• The HTTPS URL of your endpoint (e.g. https://yourapp.com/webhooks/zertiban)
• Environment: Sandbox or Production

Zertiban will register the webhook and give you the webhookSecret you'll use to verify that each notification you receive is authentic.

Endpoint requirements:

• Publicly reachable over HTTPS
• Accepts POST requests
• Responds with 2xx to acknowledge receipt (see timing and retries in Delivery & Retries)

Local development

For local development use ngrok: ngrok http 3000 gives you a public URL you can hand to Zertiban to register temporarily in sandbox.

2 Payload structure

All webhooks share the same structure. Only eventType and the resource data change. Structure verified in AbstractWebhookEventContentFactory.java:

{
  "eventUuid": "b3b3b3b3-0000-0000-0000-000000000003",
  "timestamp": "2026-04-01T09:20:00Z",
  "eventType": "OPERATION_COMPLETED",
  "metadata": {
    "apiVersion": "v1",
    "organizationUuid": "{businessUuid}"
  },
  "resource": {
    "uuid": "b7aa09fe-5678-1234-90ab-cdef98765432",
    "externalId": "OP-2026-001",
    "status": "COMPLETED"
  }
}

Payload fields

Field	Description
eventUuid	Unique event UUID. Use it to deduplicate.
timestamp	Send time in ISO 8601
eventType	Event type (see Event Reference)
metadata.apiVersion	API version (v1)
metadata.organizationUuid	Your businessUuid
resource	Operation or flow data, depending on eventType
resource.uuid	Operation or flow UUID
resource.externalId	Your externalId set on the operation or flow at creation time (invoice number, order ID, collection reference, ERP key…). Use it to reconcile against your system without storing Zertiban UUIDs.
resource.status	Current status of the operation or flow

For OPERATION_* events, resource contains the operation data. For FLOW_* events, resource contains the flow data.

Historical note: organizationUuid vs businessUuid

In previous PagaFactu documentation this field appeared as metadata.businessUuid. The current name verified against the source code is metadata.organizationUuid.

3 Headers on every request

Header	Value
User-Agent	Zertiban Webhooks Service
Content-Type	application/json
zb-timestamp	Unix milliseconds at send time
zb-signature	HMAC-SHA256, see Signature Verification

Continue with

Signature Verification

HMAC-SHA256 algorithm and examples in Java, Node and Python.

Event Reference

Catalogue of operation and flow events.

Delivery & Retries

Receiver rules, retry policy and troubleshooting.