Skip to main content

​
Webhook Delivery

​
In a nutshell

Merchant webhooks are queued as delivery records, serialized with a common envelope, sent to the tenant webhook URL, and tracked with delivery attempts.

​
Envelope

The queue serializes webhook payloads as: 
{
  "id": "delivery_uuid",
  "eventType": "invoice.paid",
  "tenantId": "tenant_uuid",
  "data": {},
  "createdAt": "2026-07-02T10:20:00Z"
}
The id is the webhook delivery ID and is also stored as the webhook_deliveries.id primary key.

​
Headers

The sender attaches:
HeaderValue
Content-Typeapplication/json
x-nombasub-eventEvent type.
x-nombasub-webhook-idDelivery ID.
x-nombasub-tenant-idTenant ID.
x-nombasub-timestampRFC3339 UTC timestamp.
x-nombasub-signatureHMAC signature when tenant webhook secret exists.

​
Signature input

Outgoing signatures hash this string: 
eventType:webhookId:tenantId:timestamp
The hash is HMAC SHA256 using the tenant webhook secret and is base64 encoded.

​
Delivery records

webhook_deliveries stores:
FieldMeaning
endpointUrlTenant webhook URL.
eventTypeNormalized event type.
payloadSerialized envelope JSON.
statusPENDING, DELIVERED, or FAILED.
retryCountAttempt counter.
maxAttemptCountDefaults to 3.
webhook_delivery_attempts stores each HTTP attempt with status code, response body, and attempt count.

​
Event data mapping

Event groupdata shape
Payment method eventsPaymentSource object.
Invoice eventsInvoice object.
checkout.createdObject with invoice and checkoutUrl.
payment_successEnriched Nomba webhook data object with subscription fields added.
Subscription eventsSubscription object.
subscription.card_expiringObject with subscription and paymentSource.

​
Delivery eligibility

A delivery is only queued when the tenant has a webhook URL and webhook secret configured.