Webhooks 🔔

Welcome to our webhooks documentation! This section outlines how the Tranzakt Payment Platform (TPP) delivers webhook notifications to your systems after payment events occur. Our webhook system ensures you receive real-time updates about payment events in your application without needing to poll our API.

Overview

Our webhook system allows you to:

Receive real-time payment notifications

Automate order fulfillment processes

Update customer accounts instantly

Track payment statuses without polling

Implement event-driven architecture

Build reliable payment flows

Webhook Architecture

After a successful payment through the Tranzakt platform, our system sends an HTTP POST request to the callback URL you specified when creating the invoice. This enables your application to react immediately to payment events as they occur.

Every webhook we send is signed with your secret key, so you can confirm the request genuinely came from Tranzakt before you act on it. See Verifying the Webhook Signature.

POST Payment Webhook

Endpoint Setup

To receive webhooks, you need to:

Create a publicly accessible HTTPS endpoint in your application

Specify this endpoint as the webhook when creating an invoice or use deafult webhook on the collection or API settings

Implement proper response handling at your endpoint

Verify the X-Tranzakt-Signature header before processing the payload

Request Details

Method: POST

Content-Type: application/json

Timeout: 30 seconds (requests taking longer will be terminated)

Headers

Header	Value	Description
`Content-Type`	`application/json`	Format of the request body
`Accept`	`application/json`	Expected response format
`User-Agent`	`Tranzakt-Payment-Platform/1.0`	Identifies our platform
`X-Webhook-ID`	UUID string	Unique identifier for the webhook event
`X-Tranzakt-Signature`	Lowercase hex string	HMAC SHA512 signature of the raw request body, signed with your secret key

Request Body

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "event": "payment.successful",
  "createdAt": "2024-05-20T10:15:30.123Z",
  "data": {
    "id": "22205053-02c7-4607-9cb5-5fa58cecae6d",
    "collectionId": "37a71e2e-ed54-4e46-a3a9-47a211c352ea",
    "collectionName": "Product Sales",
    "title": "Checkout Invoice",
    "amount": 40000,
    "totalAmount": 40400,
    "serviceCharge": 400,
    "vat": 0,
    "payerName": "John Doe",
    "payerEmail": "john.doe@example.com",
    "payerPhoneNumber": "07078955432",
    "billerName": "Example Business",
    "billerEmail": "sales@example.com",
    "billerAddress": "123 Business St",
    "type": "Live",
    "status": "Paid",
    "paymentMethod": "Card",
    "paymentDate": "2024-05-20T10:15:30.123Z",
    "billerMetaData": {
      "order-id": "12345"
    },
    "callBackUrl": "https://your-api.com/webhooks/tranzakt",
    "dateCreated": "2024-05-20T10:00:00.000Z"
  }
}

Request Body Fields

Field	Type	Description
`id`	string	Unique identifier for the webhook notification
`event`	string	Type of event that triggered the webhook (e.g., `payment.successful`)
`createdAt`	string	ISO 8601 timestamp when the webhook was generated
`data`	object	Contains the complete invoice information
`data.id`	string	Invoice ID
`data.collectionId`	string	Collection ID associated with this invoice
`data.collectionName`	string	Name of the collection
`data.title`	string	Invoice title
`data.amount`	number	Base amount in kobo/cents
`data.totalAmount`	number	Total amount including fees in kobo/cents
`data.serviceCharge`	number	Service charge in kobo/cents
`data.vat`	number	VAT amount in kobo/cents
`data.payerName`	string	Name of the payer
`data.payerEmail`	string	Email of the payer
`data.payerPhoneNumber`	string	Phone number of the payer
`data.billerName`	string	Your business name
`data.billerEmail`	string	Your business email
`data.billerAddress`	string	Your business address
`data.type`	string	Invoice type (`Test` or `Live`)
`data.status`	string	Invoice status (will be `Paid` for successful payments)
`data.paymentMethod`	string	Method used for payment (e.g., `Card`, `BankTransfer`)
`data.paymentDate`	string	ISO 8601 timestamp when payment was made
`data.billerMetaData`	object	Custom metadata you provided when creating the invoice
`data.callBackUrl`	string	The URL receiving this webhook
`data.dateCreated`	string	ISO 8601 timestamp when the invoice was created

Expected Response

Your server should respond with a 2xx status code (preferably 200 OK) to acknowledge receipt of the webhook. The response body is not used by our system.

Status: 200 OK

Verifying the Webhook Signature

Every webhook includes an X-Tranzakt-Signature header. This lets you confirm the request came from Tranzakt and that the payload was not altered in transit. Always verify it before you act on a webhook.

How the signature is generated

We compute an HMAC SHA512 hash of the exact JSON body we send, using your secret key as the HMAC key, and send the result as a lowercase hexadecimal string.

Property	Value
Header	`X-Tranzakt-Signature`
Algorithm	HMAC SHA512
Key	Your secret key
Message	The raw request body, exactly as received
Encoding	Lowercase hexadecimal

Which secret key is used

We sign with the active secret key that matches your current API mode. If your account is in test mode we sign with your test secret key, and if it is in live mode we sign with your live secret key. You can find both in your dashboard under API settings.

Use the same key on your side. If you handle both modes on one endpoint, choose the key using the data.type field in the payload, which is Test or Live.

Important

Hash the raw request body exactly as you received it. Do not parse the JSON and serialise it again before hashing. Our payload is sent formatted, so any reserialisation will change the bytes and the signature will not match. Most frameworks discard the raw body by default, so you usually need to capture it explicitly. The example below shows how.

Compare the two values using a timing safe comparison rather than a plain string equality check.

Node.js (Express) verification

PHP verification

Python (Flask) verification

C# (ASP.NET Core) verification

Implementation Notes

Idempotency: The same webhook may be sent multiple times if we don't receive a timely response. Implement idempotency using the webhook id to prevent duplicate processing.

Retry Logic: We will retry failed webhook deliveries (non-2xx responses or timeouts) up to 3 times with exponential backoff.

Webhook Security: We recommend validating the webhook source by:

Verifying the X-Tranzakt-Signature header on every request, and rejecting anything that does not match

Using HTTPS for your endpoint

Implementing IP allowlisting (contact support for current IP ranges)

Verifying the webhook data against your database records

Timeout: Webhooks must be processed within 30 seconds, or the connection will be terminated. For long-running tasks, acknowledge the webhook quickly and process asynchronously.

Keep your secret key private: Your secret key is what proves a webhook came from us. Never expose it in client side code or commit it to source control. If you believe it has been exposed, rotate it in your dashboard, and remember that webhooks are signed with the new key from that point on.

🔐 Security Note: Always validate incoming webhooks to ensure they originate from Tranzakt before processing them. Verifying the X-Tranzakt-Signature header is the strongest way to do this.

Code Example

Node.js (Express) Implementation

Event Types

Event Type	Description
`payment.successful`	Sent when a payment is successfully completed

More event types will be added in future releases.

Troubleshooting

If you're not receiving webhooks as expected:

Check your callback URL: Ensure it's publicly accessible and correctly specified when creating invoices

Verify your endpoint: Test it with tools like Postman to confirm it can receive POST requests

Check response codes: Your endpoint must return a 2xx status code within 30 seconds

Review logs: Examine your logs for any errors in webhook processing

Contact support: If issues persist, contact Tranzakt support for assistance

If the signature never matches:

Check you are hashing the raw body: Reserialising the parsed JSON will change the bytes and break the signature. Capture the raw body before your JSON parser touches it.

Check you are using the right key: Test mode webhooks are signed with your test secret key, live mode with your live secret key.

Check the encoding: The signature is lowercase hexadecimal, not base64.

Check you are using SHA512: SHA256 will produce a shorter value that never matches.

⚠️ Remember that webhooks are only delivered if your endpoint is accessible from the internet. Local development servers may need to use a tunneling service like ngrok.

For more assistance, email support at hi@tranzakt.finance

Overview#

Webhook Architecture#

POST Payment Webhook#

Endpoint Setup#

Request Details#

Headers#

Request Body#

Request Body Fields#

Expected Response#

Verifying the Webhook Signature#

How the signature is generated#

Which secret key is used#

Important#

Node.js (Express) verification#

PHP verification#

Python (Flask) verification#

C# (ASP.NET Core) verification#

Implementation Notes#

Code Example#

Node.js (Express) Implementation#

Event Types#

Troubleshooting#