Webhooks

Use webhooks to get notified about payment events.

What is a webhook

Webhooks are a very important part of our payment process. We use webhooks to share information about an event that happened. These events could range from transactions updates to fraud rule triggers.

For security reasons the event details we send to you contain only a very small portion of information about that particular event.

Type of webhooks

  • Transaction updates
  • Refund updates
  • Chargeback updates
  • Tag rule trigger
  • Anti fraud rule trigger

Sample webhook

This is a sample webhook for a transaction update:

{
    "type": "transaction",
    "id": "c3c5ee57-25bd-4e98-b328-809417924f1d",
    "status": "SETTLEMENT_REQUESTED"
}

Webhook parameters

Field Optional Description
type no Type of item this webhook is connected to
Options: transaction, refund, chargeback, validationruleset
id no Item id of the item this webhook is connected to
status yes The status change this webhook communicates
Options are based on type;
transaction: INITIATED, IN_PROGRESS, PENDING, AUTHORIZED, SETTLEMENT_REQUESTED, SETTLEMENT_COMPLETED, DECLINED, FAILED, UNKNOWN, ABANDONED, CANCELLED, AUTHORIZATION_VOIDED
refund: PENDING, PROCESSED, CANCELLED, FAILED, UNKNOWN
chargeback: OPEN, IN_DISPUTE, WON, LOST, CANCELLED
status_reason yes Status reason details. Example; the reason why a transaction has been declined

Integrating webhooks

You can configure transaction, refund and chargeback webhooks via the payment profile object.
See: API documentation.

Alternatively, it's possible to set the webhook url per transaction (Start transaction).
Transaction field: webhook_transaction_update.

Receiving a webhook

When the webhook is sent to the merchant's URL we expect the merchant's server to respond with a status code 200 - OK.

If the webhook is not successfully received we will attempt to resend the webhook in:
1m, 2m, 5m, 15m, 30m, 1h, 2h, 6h, 24h.

Validating a webhook

To ensure that the Webhook originated from ShefaPay, all our Webhooks are digitally signed.

Read more about webhook signature verification