Webhooks
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:
- Extract the Signature: Retrieve the
x-waza-signaturevalue from the header of the incoming request. - Generate Expected Signature: Compute an HMAC with SHA-256 on the received payload using your
customer secretas the key. - 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:
- 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.
- 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
| Parameter | Type | Description |
|---|---|---|
| url | string | The URL endpoint where the webhook notifications are sent. This must be an HTTPS endpoint for security purposes. |
| secret | string | A 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_events | array | An 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
| Parameter | Type | Description |
|---|---|---|
| id | string | Unique identifier for the webhook configuration. |
| created_at | date TimeStamp | Timestamp indicating when the webhook was created. |
| updated_at | date TimeStamp | Timestamp indicating the last update to the webhook. |
| state | string | The current state of the webhook (ENABLED or DISABLED). |
| url | string | The configured URL endpoint where the webhook notifications are sent. |
| secret | string | The configured secret used for verifying webhook payloads. |
| enabled_events | array | List of events for which the webhook will trigger |
Note:
Never expose your
customer secret. Use it server-side exclusively for the verification process.
Updated about 1 year ago