Webhooks allow your system to receive real-time notifications when events occur in your Trustist account. When an event happens, we’ll send an HTTP POST request to your specified webhook URL with details about the event.
Setting Up Webhooks
1. Navigate to API Settings: In TrustistTransfer, go to Settings → API Keys
2. Configure Webhook URL: Enter your webhook endpoint URL (must be HTTPS for production)
3. Select Events: Choose which events you want to receive:
– Payment Created: Triggered when a payment is initiated
– Payment Completed: Triggered when a payment is successfully processed
– Payment Failed: Triggered when a payment fails (note: failed payments can be retried by your customers)
– Standing Order Created: Triggered when a standing order is set up
– Standing Order Updated: Triggered when a standing order is modified
– Standing Order Cancelled: Triggered when a standing order is cancelled
Webhook Format
Webhooks are sent as HTTP POST requests with a JSON payload. Your endpoint should return a 2xx status code to confirm receipt.
Payment Event Example
{
“merchantId”: “your-merchant-id”,
“paymentId”: “pmt_123456789”,
“orgId”: “org_987654321”,
“created”: “2024-01-15T14:30:00Z”,
“status”: “COMPLETED”,
“amount”: 150.00,
“currency”: “GBP”,
“description”: “Product purchase”,
“reference”: “ORDER-12345”,
“paymentMethod”: “Bank Transfer”,
“eventType”: “payment.completed”
}
Standing Order Event Example
{
“merchantId”: “your-merchant-id”,
“standingOrderId”: “so_123456789”,
“orgId”: “org_987654321”,
“created”: “2024-01-15T14:30:00Z”,
“status”: “ACTIVE”,
“amount”: 50.00,
“currency”: “GBP”,
“frequency”: “MONTHLY”,
“description”: “Monthly subscription”,
“reference”: “SUB-12345”,
“eventType”: “StandingOrderCreated”
}
Event Types
Payment Events
– payment.created: A payment has been initiated by your customer
– payment.completed: A payment has been successfully processed and funds will be transferred
– payment.failed: A payment attempt has failed. *Important*: Customers can retry failed payments, so a failed payment may later become completed
Standing Order Events
– standing_order.created: A new standing order has been set up
– standing_order.updated: An existing standing order has been modified
– standing_order.cancelled: A standing order has been cancelled
Webhook Delivery
– Retry Policy: We automatically retry failed webhook deliveries up to 3 times with increasing delays (1s, 3s, 10s)
– Success Response: Your endpoint should return a 2xx HTTP status code
– Failure Handling:
– 4xx responses (client errors) are not retried
– 5xx responses (server errors) and network failures are retried
– Timeout: Webhook requests timeout after 30 seconds
Security Considerations
– HTTPS Required: Production webhook URLs must use HTTPS
– IP Whitelisting: Consider restricting access to webhook endpoints to Trustist’s IP ranges
– Validation: Validate the webhook payload format and expected fields
– Idempotency: Design your webhook handler to be idempotent – we may send the same event multiple times
Testing Webhooks
1. Use a Testing Tool: Services like ngrok can expose your local development server for testing
2. Webhook Inspector: Use tools like webhook.site or requestbin.com to inspect webhook payloads
3. Logging: Log all incoming webhooks for debugging and monitoring
4. Error Handling: Test how your system handles malformed or unexpected webhook payloads
Common Integration Patterns
Order Status Updates
Use payment webhooks to update order status in your system:
– `PaymentCreated` → Set order to “Payment Pending”
– `PaymentCompleted` → Set order to “Paid” and trigger fulfilment
– `PaymentFailed` → Set order to “Payment Failed” (but keep available for retry)
Subscription Management
Use standing order webhooks to manage subscriptions:
– `StandingOrderCreated` → Activate subscription
– `StandingOrderCancelled` → Cancel subscription or mark for cancellation
Customer Communication
Trigger customer emails or notifications based on payment events:
– Send confirmation emails on `PaymentCompleted`
– Send retry prompts on `PaymentFailed` (if retry suppression is not enabled)
Error Handling
If your webhook endpoint is unreachable or returns errors:
– View Webhook History: Check the webhook delivery log in your Trustist portal
– Monitor Status Codes: Failed deliveries show the HTTP status code returned
– Check Payload: Review the exact payload that was sent
– Retry Manually: Some failed webhooks can be manually retried from the portal
Best Practices
1. Process Quickly: Keep webhook processing fast (under 10 seconds) to avoid timeouts
2. Queue Heavy Work: For complex processing, acknowledge the webhook quickly and queue the work
3. Handle Duplicates: Events may be sent multiple times – use payment/order IDs to detect duplicates
4. Validate Data: Always validate webhook payloads before processing
5. Monitor Webhook Health: Set up monitoring to detect webhook delivery failures
6. Test Thoroughly: Test webhook handling for all event types and edge cases
Troubleshooting
Common Issues
Webhooks Not Received
– Check your webhook URL is correct and accessible
– Verify your server returns 2xx status codes
– Check firewall and security settings
Duplicate Webhooks
– This is normal behaviour – implement idempotency checks
– Use the payment/standing order ID to detect duplicates
Failed Deliveries
– Check webhook logs in your Trustist portal
– Verify your endpoint handles the payload format correctly
– Ensure your server responds within 30 seconds
Getting Help
If you need assistance with webhook integration:
– Contact our technical support team with specific error details
– Provide example webhook payloads that are causing issues
