How webhooks work
1
Create an endpoint
Register a webhook endpoint URL and choose which events to subscribe to. You can subscribe to specific events or use
["*"] to receive all events.See the webhook endpoints API reference for CRUD operations.2
Store the signing secret
When you create an endpoint, TRXN returns a signing secret (format:
whsec_<64_hex_chars>). Store this securely — it is only shown in full once, at creation time.3
Receive events
When a subscribed event occurs, TRXN sends an HTTP POST request to your endpoint with a JSON payload describing the event.
4
Verify and process
Your server verifies the request signature, returns a 2xx response, then processes the event asynchronously.
Payload format
Every webhook delivery sends a JSON body with this structure:Signature verification
TRXN signs every webhook request with HMAC-SHA256 so you can verify that the request genuinely came from TRXN.Signature header format
Every webhook request includes anX-Trxn-Signature header:
Verification steps
- Extract the timestamp (
t) and signature (v1) from the header - Check that the timestamp is within 5 minutes of the current time (prevents replay attacks)
- Compute the expected signature:
HMAC-SHA256(secret, "<timestamp>.<raw_body>") - Compare signatures using constant-time comparison
Use the full signing secret including the
whsec_ prefix as the HMAC key. This matches Stripe’s implementation pattern.Code examples
Available events
Customer events
Product events
Price events
Invoice events
Subscription events
Subscription phase events
Payload example:
Wallet events
Crypto address events
Payment claim events
Crypto transaction events
Transaction allocation events
Response handling
Your endpoint must respond with a 2xx status code to indicate successful receipt. If your endpoint returns a non-2xx status code, TRXN retries with exponential backoff for up to 11 attempts.Error handling
Event retention
TRXN retains webhook events for 30 days.Best practices
- Respond quickly — return a 2xx response before any complex logic that could cause a timeout. Process the event asynchronously after responding.
- Handle duplicates — webhook endpoints may occasionally receive the same event more than once. Make your event processing idempotent by tracking the
idfrom the payload. - Handle out-of-order delivery — events may not arrive in chronological order. Use the
timestampfield to determine the sequence rather than assuming arrival order. - Always verify signatures — use the
X-Trxn-Signatureheader to verify all incoming webhooks. Reject any webhook that fails signature verification. - Use HTTPS — always use HTTPS endpoints for security.
- Store secrets securely — store your signing secrets in environment variables or a secrets manager, never in source code.
- Monitor failures — check webhook events in the dashboard to monitor delivery status.
- Regenerate compromised secrets — if you suspect your signing secret has been compromised, regenerate it immediately via the API.