Webhooks allow you to subscribe to product and service transaction event that happens in your Patronize merchant account. When an event gets triggered, we'll send a HTTP POST payload to your configured URL.

Webhooks are useful for setting up integrations, syncing a database with Patronize endpoint service

Our webhooks provide real-time notifications when an transactional event happens on your account. These events could range from a successful transaction to a failed transaction.

Some examples of events that trigger the webhook are:

• When you receive a settlement transaction.
• When you perform a successful payout transaction to Pocket.

Some examples of things you could do with our webhooks include

• Notify a customer when payment is successful or unsuccessful

In order to receive these notifications, you need the following:

• An endpoint on your server that will be called by us to send you notifications
• Webhook enabled on your Patronize dashboard.

Payload

Webhook events payload are formatted in JSON. See more:

The webhook event object

{
  type: 'item-sale.success',
  uuid: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  amount: 80000,
  actual_amount: 80000,
  settled_amount: 79600,
  description: 'Payment for Order',
  fees: 400,
  paypoint: false,
  customer: {
    uuid: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
    tag: 'adxvi',
    frequency: 50
  },
  meta: {
    order_id: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
    item_type: 'services',
    delivery_fee: 0,
    delivery_instruction: null,
    landmark: null,
    street_address: null,
    recipient: null,
    identifier: '"airlinerId"',
    meta: {
      provider_reference: 'abeg_p2p_xxxxxxxxxxxxxxx',
      provider: 'Abeg',
      identifier: '"airlinerId"',
      business_name: 'ABC Global',
      item_id: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
      qty: 1,
      delivery_area_name: '',
      delivery_fee: 0,
      processing_fee: 0,
      order_type: 'services',
      voucher_used: false,
      voucher_amount: 0,
      meta: [Object]
    }
  }
}

Attributes

order_id

UUID

The unique id of the webhook event

webhookId

UUID

The ID of the webhook this webhook event is linked to

actual_amount

INTEGER

The actual_amount is the kobo value of the naira amount inputted by the customer/user.

customer

Object

The customer object contains customer/user data, For Example: name,email etc.

meta

Object

Meta contains the order data like ‘identifier’, which is preconfigured on service and products Advanced settings on Patronize dashboard ...etc.

Privacy

Webhooks will only send objects that are accessible to all members of a workspace. This means that private tasks will be redacted, and their activities will not be sent.

Event handling

Delivery attempt

A webhook endpoint should return a HTTP status code 2xx if the webhook was correctly handled. This will let us know we shouldn't retry sending the event.

All webhook events are sent through a POST request with a application/json body.

Retry logic

If your server isn't reachable, or isn't returning a correct status code, Patronize will try resending the webhook again up to 5 times within 3 days.

Order of events

Patronize doesn't guarantee events will be ordered, and your service should take this into account.

Duplicate events

In the unlikely event we don't receive your endpoint response while sending you a webhook, we may try resending the same webhook event later. Your service should be designed to handle duplicate events from Patronize webhooks.