Skip to main content

Webhook API

Incoming webhooks provide server based method to trigger processing based on real-time network activity

BOPP uses webhooks to notify a REST based application when an events happens for a subscription. Webhooks are useful for processing asynchronous events like a customer initiating payment via a bopp button, or QR code. They can also be used for receiving notifications of other notifications such as payment confirmations, failures and other general subscription activities.

BOPP Webhook API's are provided as a to complement the BOPP reporting API which allows external services to query BOPP network events on demand.

What are webhooks

A webhook enables BOPP to push real-time notifications to your application. BOPP uses HTTPS to send these notifications to your app as a JSON payload. These notifications cane be used to execute actions in connected backend systems.

Usage Examples

The webhook API is intended to service two main use cases.

  • To Provide Summary level events associated with user interactions (e.g. Paying via a BOPP Checkout, QR or Paylink)
  • To provide detailed information about the full lifecycle of a network transaction

The first case is expected to alow for easy integration for payment flow integrations which are primarily interested in providing additional processing once a payment has been made. The second case is expected to enable the development of rich web applications which can provide an alternative user experience to the existing BOPP App and BOPP merchant dashboard.

Steps to receive webhooks

You can start receiving event notifications in your app using the steps in this section:

  • Identify the events you want to monitor and the event payloads to parse.
  • Create a webhook endpoint as an HTTP endpoint (URL) on a dev server, register it with the BOPP sandbox using the registration API.
  • Handle requests from BOPP by parsing each event object and returning 2xx response status codes.
  • Test that your webhook endpoint is working properly using the BOOP sandbox.
  • Deploy your webhook endpoint so it’s a publicly accessible HTTPS URL.
  • Register your publicly accessible HTTPS URL using the registration API or Admin section of the BOPP dashboard.

What is a webhook endpoint

Creating a webhook endpoint is no different from creating any other website page or REST service. It’s an HTTP or HTTPS endpoint on a server with a URL. If you’re still developing your endpoint on a dev machine and using the BOPP sandbox, it can be HTTP. After it’s publicly accessible, it must be HTTPS. You can use one endpoint to handle several different event types at once, or set up individual endpoints for specific events.

Webhook Server Responses

The BOPP webhook server expects the endpoint it calls to quickly return a successful status code (2xx). So your webhook handler should return this prior to undertaking any complex logic that could cause a timeout. For example, you must return a 200 response before updating a customer’s invoice as paid in your accounting system.

Built-in retries

BOPP webhooks have built-in retry methods for 3xx, 4xx, or 5xx response status codes. Otherwise if BOPP doesn’t quickly receive a 2xx response status code for an event, the event will be marked as failed and will stop stop trying to send it to the receiving endpoint.

Webhook Registration

The webhook registration API allows webhooks to be programmatically registered and unregistered. This is done as described below via a REST api endpoint on the BOPP network.

Where:

  • network = the bopp network being addresses .io, .dev for prod and test
  • api = the API to attach the webhook to. (bopp-checkout or reporting)|

Create Webhook

    POST https//api.$(network)/$(api)/v1/webhook

The body of the post request should be a json message which contains the following elements

NameDescription
urlThe URL of the webhhook to be called. This URL must be addressable by the BOPP network and should process POST requests.
...The remaining elements are API specific and will be outlined in the section below
partiesA Map of { partyrole: partyId } values which specify the parties which will trigger this webhook

The return from this post method will return a webhookid which can be used to update or remove the webhook as specified below.

Update Webhook

Calling this method will cause the webhook to be updated. The body of this request should be the same as for the POST request above.

    PUT https//api.$(network)/$(api)/v1/webhook/$(webhookId)

Remove Webhook

This method will cause the webhook to be deleted. Once completed no further calls will be made to the webhook.

    DELETE https//api.$(network)/$(api)/v1/webhook/$(webhookId)

Available Webhook API's

The following sections describe the webhook API's available for specific BOPP APIs. Details of the underlying API interactions can be found in the associated API documentation.

BOPP Checkout

When registered the bopp-checkout webhook will be triggered as a user makes a payment.

Registration Elements

NameDescription
urlThe URL of the webhhook to be called. This URL must be addressable by the BOPP network and should process POST requests.
eventsPaymentInitiated, PaymentInProcess, PaymentSuccess, PaymentFailed
partiesA Map of { partyrole: partyId } values which specify the parties which will trigger this webhook

Events

####PaymentInitiated This is triggered when the user scans a QR code, follows a paylink, or presses the bopp checkout button on the UI.

####PaymentInProcess This is triggered when the user starts to initiate a payment with their bank application

####PaymentSuccess Triggered when the bank confirms payment to the user via the BOPP network

###PaymentFailed Triggered if at any point after the initial payment process the flow is abandoned or fails

Reporting

When registered the reporting webhook is triggered when a network resource is updated. It will receive the same data that is returned by the reporting API.

Registration Elements

NameDescription
urlThe URL of the webhhook to be called. This URL must be addressable by the BOPP network and should process POST requests.
resourceThis the resource PaymentRequest, PaymentInstruction, PaymentReport to be received
statesA comma separated list of state triggers which will cause the webhook to be called
partiesA Map of { partyrole: partyId } values which specify the parties which will trigger this webhook