Skip to main content
Pasteaza sends webhook notifications to your configured webhook URL when important transaction events happen on your account. Webhooks are delivered as HTTPS POST requests with a JSON payload.
Always verify the webhook signature before you trust or process the payload.

​
Configure your webhook URL

Configure your webhook endpoint in your Pasteaza merchant dashboard. Your endpoint should be publicly accessible over HTTPS. 
https://merchant.com/api/pasteaza/webhook

​
Webhook events

Pasteaza currently supports these webhook events:
EventDescription
account.creditMoney has been credited to your merchant account.
account.debitMoney has been deducted from your merchant account.
virtual_account.transferA customer has successfully transferred funds to a generated virtual account.

​
Sample payload

{
  "event": "virtual_account.transfer",
  "data": {
    "reference": "pst_txn_01JABCXYZ",
    "amount": 5000,
    "currency": "NGN",
    "status": "successful",
    "account_number": "1234567890",
    "sender_name": "John Doe"
  }
}

​
Signature verification

Each webhook request includes an X-Pasteaza-Signature header. 
X-Pasteaza-Signature: 8b3f8c...
Generate an HMAC SHA-256 hash of the raw request body with your webhook secret. Compare the generated hash with the value in the X-Pasteaza-Signature header. Only process the webhook when both values match.
Use the raw request body for signature verification. Do not verify a parsed or modified JSON object.

​
Verification flow

1

Receive the webhook

Accept the incoming HTTPS POST request on your webhook endpoint.
2

Read the signature header

Get the value of the X-Pasteaza-Signature header from the request.
3

Hash the raw body

Generate an HMAC SHA-256 hash from the raw request body using your webhook secret.
4

Compare signatures

Compare your generated hash with the signature header value.
5

Process the event

Process the webhook only after the signature is valid.

​
Retry policy

If your server does not return a successful 2xx HTTP response, Pasteaza will automatically retry delivery. Design your webhook handler to be idempotent so repeated events do not update the same transaction more than once.

​
Best practices

  • Always verify the webhook signature.
  • Return a 2xx response after successful processing.
  • Store processed webhook references to prevent duplicate processing.
  • Fetch the related transaction from the API when you need the latest state.
  • Never trust webhook payloads without signature verification.
  • Keep your webhook secret secure and rotate it after any suspected exposure.

Authentication

Learn how to authenticate API requests with your secret key.

Idempotency

Prevent duplicate processing when requests or events are retried.