Webhooks
Receive real-time notifications for user and transaction events
Webhooks allow you to receive real-time notifications when events occur in your Paytrie integration. Instead of polling the API for updates, webhooks push event data to your server as events happen.
Available webhooks
| Webhook | Trigger |
|---|---|
| User Verified | When a user completes KYC verification |
| Transaction Initiated | When a new transaction is created |
| Transaction Complete | When a transaction finishes processing |
| Transaction Status Update | When a transaction status changes |
Setting up webhooks
To receive webhooks, you need to:
- Create POST endpoints on your server to receive webhook payloads
- Register your webhook URLs using the API (see below)
You can configure separate URLs for each webhook type, or use a single endpoint that handles all webhook types.
Get current webhook configuration
curl "https://api.paytrie.com/webhooks" \
-H "x-api-key: your-api-key"API Reference: Get Webhooks
View complete request parameters and response schema
Update webhook configuration
curl -X PATCH "https://api.paytrie.com/webhooks" \
-H "x-api-key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"verifiedEmailEnabled": true,
"verifiedEmailUrl": "https://your-server.com/webhooks/user-verified",
"transactionInitiatedEnabled": true,
"transactionInitiatedUrl": "https://your-server.com/webhooks/tx-initiated",
"transactionCompleteEnabled": true,
"transactionCompleteUrl": "https://your-server.com/webhooks/tx-complete",
"transactionStatusUpdateEnabled": true,
"transactionStatusUpdateUrl": "https://your-server.com/webhooks/tx-status"
}'API Reference: Update Webhooks
View complete request parameters and response schema
Your webhook endpoints must be publicly accessible via HTTPS and respond with a 2xx status code to acknowledge receipt.
Webhook payloads
All webhooks are sent as POST requests with a JSON body.
User verified
Triggered when a user completes KYC verification and is ready to transact.
{
"email": "user@example.com",
"status": "verified"
}Transaction initiated
Triggered when a new transaction is created.
{
"email": "user@example.com",
"txId": "3943bb00-1551-4f1d-bf32-2d82608bc15e",
"status": "pending request money transfer"
}Transaction complete
Triggered when a transaction completes successfully.
{
"email": "user@example.com",
"txId": "3943bb00-1551-4f1d-bf32-2d82608bc15e",
"status": "complete"
}Transaction status update
Triggered whenever a transaction status changes. This provides more granular tracking than the initiated/complete webhooks. See Transaction statuses for all possible values.
{
"email": "user@example.com",
"txId": "3943bb00-1551-4f1d-bf32-2d82608bc15e",
"status": "processing request money transfer"
}Payload fields
| Field | Type | Description |
|---|---|---|
email | string | The user's registered email address |
txId | string | The unique transaction ID (present for transaction webhooks) |
status | string | The current status |
Best practices
Respond quickly
Return a 2xx response immediately, then process the webhook asynchronously
Log payloads
Log all webhook payloads for debugging and auditing
Webhooks are sent once and not retried. Ensure your endpoint is reliable and returns a 2xx status code promptly.