Event Notifications

Webhooks

Webhooks deliver asynchronous event notifications from Payblr to your system so you can update records, notify users, or trigger downstream processing without polling.

Updated 15 minutes ago

On this page

Overview How it works Sequence diagram Management capabilities API Explorer Reference Delivery & reliability Event codes Payload reference Implementation checklist Next steps

Overview

Use Payblr APIs to register a webhook endpoint, subscribe to event types, and recover historical or missed notifications when needed.

Before enabling webhooks, expose a stable URL that can receive HTTP payloads from Payblr and process the event details.

Webhook payloads are not EHI payloads. Webhooks are event notifications and do not require your system to return an approve or decline authorization decision.

How it works

High-level delivery flow from endpoint setup through acknowledgement.

Create webhook endpoint

Define subscribed events

Select the event types your system needs to process.

Receive webhook notification

Payblr sends an HTTP payload to your endpoint when a subscribed event occurs.

Acknowledge and process

Validate the request, process the event, and return a successful acknowledgement.

Webhooks Sequence Diagram

Recommended webhook delivery sequence

Event

Payment Event

Platform

Payblr Webhooks

System

Client Endpoint

1. Event occurs

Webhook event

A supported card, transaction, or lifecycle event occurs.

Payment EventPayblr Webhooks

2. Prepare webhook notification

Payblr prepares the event notification payload for delivery to the configured client endpoint.

Payblr WebhooksprocessesPayblr Webhooks

3. Send webhook

Webhook event

Endpoint

Client webhook endpoint

Method

POST [CLIENT_WEBHOOK_ENDPOINT_URL]

Payblr sends the webhook payload to the client webhook endpoint.

Payblr WebhooksClient Endpoint

4. Validate and process

Client system validates the request, processes the event payload, and stores the relevant event data.

Client EndpointprocessesClient Endpoint

5. Acknowledge receipt

Webhook event

Endpoint

Webhook acknowledgement

Method

HTTP 2xx response

Client system returns a successful acknowledgement after receiving the webhook.

Client EndpointPayblr Webhooks

6. Get undelivered notifications

Endpoint

Get Undelivered Notification Details

Method

GET /program-manager/thr/event-delivery-system/webhooks/{webhookId}/notifications/undelivered

Client system retrieves undelivered notifications when recovery is needed.

Client EndpointPayblr Webhooks

Sequence diagram showing how Payblr delivers webhook event notifications to the configured client endpoint and receives a delivery acknowledgement.

Webhook management capabilities

Capability	Purpose
Create webhook endpoints	Register the URL where your system will receive webhook notifications.
Update webhook endpoints	Maintain endpoint details as your integration changes.
Manage event subscriptions	Select the event types your system wants to receive.
Retrieve notification details	Review details for events and notifications sent to your system.
Retrieve historical or missed events	Recover event activity when your system needs to review or replay missed notifications.
Re-send notifications	Request notification delivery again when recovery or troubleshooting is required.

API Explorer Reference

Use the API Explorer to review request and response contracts for webhook management operations, starting with Create Webhook.

Open API Explorer

Delivery & reliability

If your endpoint is temporarily unavailable, delivery may be retried. Process repeated notifications idempotently using a stable notification identifier when available.

Use historical or missed-event retrieval when recovery, replay, audit, or reconciliation is required.

Event codes

Event code	Description	When it is sent
`101`	Fraud rule triggered by a transaction.	When a fraud rule is triggered.
`102`	Fraud alert closed by API confirmation or after 3 days.	When a fraud alert is closed, acknowledged, or times out.
`103`	Card status change notification. May also include an EMV chip block script for irreversible statuses.	When a card status changes.
`104`	Customisable PAN created.	When a card with a custom PAN is created.
`105`	Manual payment review outcome.	When a pending payment is reviewed in fraud or scam monitoring.
`106`	Tokenisation Authorisation Request (TAR).	When a tokenisation authorisation request is received.
`107`	Activation Code Notification (ACN).	When an activation code notification is generated.
`108`	Tokenisation Complete Notification (TCN).	When tokenisation has completed.
`109`	Tokenisation Event Notification (TEN).	When a tokenisation lifecycle event occurs.
`110`	Failed token status change.	When a token status update fails.
`112`	Transaction confirmation.	When a transaction confirmation event occurs.
`115`	Fraud Transaction Monitoring (FTM) alert created.	When a new fraud monitoring alert is created.

Webhook payload reference

Payblr sends webhook notifications to your configured endpoint when a subscribed event occurs exactly as it is received.

Route each notification by context.eventCode and use context.notificationId for duplicate detection.

Standard payload structure

Webhook notifications use a standard structure with a context object and an event-specific payload object.

{
  "context": {
    "notificationId": "notification-uuid",
    "eventCode": 103,
    "eventVersion": "v1",
    "notificationTime": "2026-06-09T16:15:30Z"
  },
  "payload": {
    "eventSpecificField": "eventSpecificValue"
  }
}

Payload examples by event code

Implementation checklist

Use this checklist before enabling webhooks in an environment. Concept details are covered earlier on this page; this section is the readiness pass only.

Area	Checklist item
Endpoint readiness	Expose a stable webhook endpoint that Payblr can reach and that can receive HTTP payloads.
Event subscription	Select and configure the required event types for the endpoint.
Event mapping	Map each event code to the correct internal processing workflow.
Request validation	Validate webhook requests before processing the payload.
Acknowledgement	Return a successful acknowledgement quickly after receiving the notification.
Idempotency	Process repeated notifications safely using a stable notification identifier when available.
Scope boundary	Do not use webhook responses to approve or decline transactions, and do not treat webhook payloads as EHI authorization payloads.
Recovery	Understand historical or missed event retrieval for recovery and reconciliation.
Logging	Store notification identifiers, event codes, timestamps, payload references, and processing outcomes for troubleshooting.

Next steps

After implementing webhooks, continue with 3D Secure Authentication or Click to Pay depending on your program requirements.