Webhooks
A Webhook is a registered URL endpoint that you define, that our servers will call when the specified action occurs on our system.
Webhooks allow for instant notification of awaiting requests for your account, and in many cases, removes the need for you to constantly poll our API for new requests. Webhook notifications don’t expose any transaction related data. The registered URL will be called only once for any registered event. The expectation is that this is a trigger for your system to pull pending requests.
The supported Webhook poll actions are:
Transaction Request – this notification is triggered when a new transaction arrives for processing.
Cancellation request – this notification is triggered when a transaction cancellation request is raised.
Change Beneficiary Request – this notification is triggered when a customer wishes to change the beneficiary/recipient details for an existing transaction.
Transaction Status Request – this notification will be triggered when we require a status update for a transaction that you are processing on your system. We typically use this when a transaction is processed asynchronously, or when a transmission error occurs during processing.
The endpoint that you register will be called with the URL that you specify. We recommend that you use the https protocol for your endpoints, but we will support http.
Please note: no sensitive information (i.e. transaction body or transaction id) will be sent along with the Webhook call-back.
For the endpoint host, you can use either a DNS resolved name or a public IPv4 address. Private IPv4 address, and IPv6 addresses, are not supported.
If you supply a https secured remote endpoint, you can also specify that we sign the outgoing request, using our mutual-SSL certificate.
The call-back will be a HTTP GET request to the URL that you specify. Http redirects will not be allowed. If you specify a https endpoint, we will check for a valid TLS certificate and confirm that it has not been revoked. If your TLS certificate is not valid, the call will be aborted. Your web server will need to support TLS 1.2 or higher.
Note: Depending on the integration product Webhooks will be mandatory to register.
The diagram above shows how a Webhook can be used. We first register the Webhook to inform the WorldRemit systems which event types you wish to receive notifications for. Then when an event occurs that matches your registration, such as a new transaction being ready to process, the system will call your URL endpoint to inform you.
You will then call the standard ‘Awaiting’ methods for the type of event required: Transaction, Cancellation, Change Beneficiary, Transaction Status, etc.