Webhooks - Implementation and Security

What are Webhooks?

Some of our documentation will use Callback and Webhook interchangeably.

In layman's terms, a webhook is an automated message that is sent in real time via HTTP to you when something happens on Azupay's system that is important. We recommend all clients strongly consider implementing webhooks where possible when implementing Azupay to support a real time payment experience and minimise the need to poll our system for updates on transactions.

Azupay's platform uses event driven architecture, and can trigger updates to be sent to your system in real time for a subset of events across our platform.

Supported Events

Please note this list is non exhaustive, and our API specification should always contain the latest list of webhooks available.

Event Callback	Notification Object	Supported Webhook events
PaymentRequestStatus	PaymentRequest.paymentNotification	Sends an event on updates to the status of a PaymentRequest, such as a Waiting, Complete, Expired, Return In Progress, Return Complete, Return Failed or Return Rejected.
PaymentAgreementStatus	PaymentAgreement.paymentAgreementNotification	Sends an event on updates to the status of a PaymentAgreement, such as a Created, Active, Suspended or cancelled Agreement
PaymentInitiationStatusEvent	PaymentInitiation.paymentInitiationNotification	Sends an event on updates to the status of a PaymentInitiation, such as a Settled, Pending or Failed initiation attempt
PaymentStatus	Payment.paymentNotification	Sends an event on updates to the status of a Payment, such as a Created, Pending, Failed, Settled or Returned payment
SweepRequestEvent	client.sweepNotification	Sends a notification when a sweep settles into your nominated settlement account
ClientEnabledEvent	client.clientManagementNotification	Sends a notification when a sub-client of your account is enabled by our team

How to identify if an API request supports webhooks

Supported APIs will have a dedicated "CALLBACK" section, and our API Guides also specify when and how webhooks can be used for specific API requests. This section will be at the bottom of the associated API documentation, and is typically only available on the create request. Typically, webhooks will trigger when the state of an event in Azupay's system is updated, such as a Payment Request being fulfilled, a Payment Agreement being accepted or similar.

Webhook retry & delivery logic and considerations

If the target endpoint does not return HTTP "200", Azupay will retry the webhook call 45 times with a 20 second delay.
Webhooks are delivered at least once per transaction status update unless retry attempts are exhausted, and your system should cater to receiving duplicate events.
New Webhook events may be implemented for specific webhooks. Your system should cater to ingesting new webhooks gracefully and it may be useful to have internal alerting if you recieve new statuses you aren't expecting so you can review how you may want to ingest and use these statuses.

Webhook Implementation Patterns

Azupay currently supports two patterns for Webhook configuration implementation. These are transaction level and client level webhook subscriptons

Feature Comparison for Implementation Patterns

Implementation Pattern	Client Level	Transaction Level
Scope level for webhooks	Receive events for all event types across all webhook event subscriptions set for a configuration	Receive all events scoped to a specific transaction
How to enable	Raise a support request to have client level webhooks configured on your account. Note that webhooks sent in this manner do not overwrite any transaction level webhook object but are sent in parallel. We will be releasing functionality in the near future to all client self service of client level configurations.	Transaction level webhooks can be enabled on any transaction request that specifies a Callback Option on our API documentation when the transaction is created.
When to use	Use when there is a need to have a standardised configuration for webhooks across all events in your account. Note that Client level webhook configurations don't currently support per request unique authorisation headers and this should be considered if you use receipt of a webhook to process a high impact event on your system, such as order fulfilment.	Use when there is a high degree of accuracy or flexibility required with updating webhook authorisation codes and endpoints on a per request basis. Note that we don't currently support authorisation key or URL rotation on a transaction level webhook. If you need to update a specific transaction webhook
Constraints of this approach	If using API Key authorisation, a global authorisation key must be used,	Rotation of webhook endpoints and authorisation headers not possible for already created webhooks. If rotation is required, deletion or patching of the associated event may be required.
Benefits of this approach	Webhooks do not need to be configured on a per request basis. End points and authorisation information can be updated for in flight requests	Supports per request unique authorisation headers and webhook endpoints.
Authorisation options available	- API Key (Authorisation Header) - OAuth2	- API Key

Security of Webhooks

Authorization Header Uniqueness: Given your business will probably fulfill a product upon this invocation for PaymentRequests or PaymentInitiations, for security reasons it is recommended that you use an Authorization header value which is unique per transaction and is a mix of upper and lower alphabetic, numeric and symbol characters.
HTTPS: Ensure your endpoint enforces HTTPS so that requests to the endpoint can not be intercepted.
Consider OAuth2 for Client level implementations: OAuth2 allows regular rotation of tokens used for authorisation and reduces the risk of an authorization header needing to be rotated if it becomes exposed.
Use IP Whitelisting: Whitelist our API requests and block requests originating from other IP ranges to your endpoint to ensure only requests originating from Azupay can update your transactions.

Webhooks Fixed IPs

Webhook calls originate from the following fixed IP addresses:

Production IP	UAT IP
13.210.211.86	54.79.236.21
13.211.183.241	54.252.111.236
13.236.45.75	3.106.36.88

Please ensure you have whitelisted requests to your Webhook Endpoint to these IP ranges for increased security.