A guide on using webhooks with Waza Payout APIs

Webhooks provide the capability to instantly get notified about events occurring in your account. Rather than initiating an API call to gather updates, we directly send them to a designated URL endpoint you've set up. This guide gives more details about the setup, safety protocols, and management of event notifications through webhooks in our platform.

To set up, simply configure the endpoint by using create webhooks. We allow up to five ENABLED webhooks at any given time.

Security: Payload Verification

Ensuring the webhook calls are from the Waza Payout API and have not been tampered with is crucial. We employ a mechanism using HMAC with SHA-256 to sign the payload.

Verification Steps:

  1. Extract the Signature: Retrieve the x-waza-signature value from the header of the incoming request.
  2. Generate Expected Signature: Compute an HMAC with SHA-256 on the received payload using your customer secret as the key.
  3. Compare Signatures: Compare the signature from the header to the one you've computed. If they match, the request can be considered legitimate.

Retrying Failed Webhooks

Webhook deliveries might not always succeed on the first try. To address these unsuccessful attempts we have implemented some fail safes:

  1. Exponential Backoff: If a webhook delivery fails, we employ an exponential backoff strategy. This means after the first failure, we wait and try again in double the time, then double again if that fails, and so on.
  2. 72-Hour Window: We persist in our delivery attempts for up to 72 hours. If all retries fail within this time frame, we will cease delivery attempts for that particular event.

Webhook Creation Request Fields

urlstringThe URL endpoint where the webhook notifications are sent. This must be an HTTPS endpoint for security purposes.
secretstringA secret string that MyAPI will use to generate a signature for each webhook event. This ensures the authenticity of the events sent to the URL endpoint.
enabled_eventsarrayAn array of event names that you want to receive notifications for. Possible values include (but are not limited to) transaction.created, transaction.processing, etc.

Webhook Creation Response Fields

idstringUnique identifier for the webhook configuration.
created_atdate TimeStampTimestamp indicating when the webhook was created.
updated_atdate TimeStampTimestamp indicating the last update to the webhook.
statestringThe current state of the webhook (ENABLED or DISABLED).
urlstringThe configured URL endpoint where the webhook notifications are sent.
secretstringThe configured secret used for verifying webhook payloads.
enabled_eventsarrayList of events for which the webhook will trigger



Never expose your customer secret. Use it server-side exclusively for the verification process.