Guides

Webhooks

To view webhooks for specific products please use the following pages:

Setting Up Webhooks

Webhook notifications are Yaspa's main method of sending updates to merchant servers. webhook notifications are HTTPS POST requests and will be sent in real time as a customer proceeds with a payment, or the collaborating banks return an update on the progress of Payments.

For security reasons, it is important that any business action taken as part of a payment must be triggered off of webhooks and not any of the client-side interactions or redirect URLs. Webhooks will also be signed, allowing merchants to verify any webhook notification they receive. See the section below.

Merchants can configure webhooks in the admin dashboard. Here they can set which webhook events they wish to receive and what URLs they would like these webhooks sent.

webhooks must be integrated as part of a Yaspa integration.

Webhook Processing

Webhooks are sent from Yaspa to the merchant via HTTP requests. The merchant server must respond with an HTTP 200 OK to confirm receipt.

Failure to respond, or receiving error codes such as 503 (Gateway Timeout) or 429 (Too Many Requests), triggers retries. Yaspa will attempt a number of retries with exponential backoff in these scenarios.

⚠️

Warning

Strict parsing should never be used on Yaspa webhooks. Yaspa will be adding additional fields to the json over time.

Reconciliation and Idempotence

Idempotence is an ID that makes sure if something is sent twice, it can be highlighted

Check the ID, if never seen before then change status, if you have seen it before can ignore.

concept used to allow for the chance request is sent twice.

HTTP requests can be retried

Merchants need to reconcile the webhook back to the pay-in instruction which launched the original journey to release goods and service. Any of the following fields passed into the instruction can be used:

  • reference – The reference can be used as this is unique
  • searchableText – A string passed in the 'searchableText' field
  • payload – Any data from the payload

Because of the retry logic, webhooks may also be sent more than once. Merchants should assure duplicate webhooks don't cause issues in their system. Any of the following fields can be used as idempotence IDs to deal with duplicate messaging.

Webhook Security

As webhooks will drive payment decisioning, merchants should take care to secure webhook traffic between their servers and Yaspa.

Webhook IP Whitelisting

Yaspa will send webhooks to the merchant server from a range of IPs. Merchants can choose to only allow Yaspa webhooks from these IPs. Yaspa integration managers will provide a range of IPs to merchants upon request as part of onboarding.

Verifying Webhooks

For security reasons — all webhook notifications should be verified to ensure they originate from Yaspa and that they have not been altered in transit.

Yaspa will sign all webhooks using a Yaspa private key before the message is sent. Merchants can use Yaspa's public key to verify the webhook is authentic. All data within the webhook is included in the signature, so any alteration will result in verification failure.

Verification Steps:

  1. Get the Yaspa Public Signing Key:
    1. Production: https://api.yaspa.com/v2/merchant/citizen-signing-public-key
    2. Test: https://testapi.yaspa.com/v2/merchant/citizen-signing-public-key
  2. Decode the public key to UTF-8 from Base64
  3. Generate a public key using the decoded key extracted from step 2
  4. Extract the header of the Webhook-Signature from the webhook
  5. Extract the body of the webhook
  6. Verify the result by passing the webhook signature

A full worked example is available within the Recipes.

Configure Your Webhook URL:

  1. Log in to your admin dashboard.
  2. Navigate to the Webhooks section under settings. Provide the URL of your endpoint where you want to receive event notifications.
  3. Select the events you want to be notified about (e.g., payin success, payin failed).
  4. Save your changes.
  5. Test your webhook.
  6. Use Yaspa's dashboard to send a test event to your webhook URL and confirm that your application processes it correctly.

Updated 4 months ago