Skip to main content
Webhooks allow your application to receive real-time HTTP notifications when events occur in your TRXN account. Instead of polling the API for changes, you register a URL and TRXN sends a POST request to that URL whenever a relevant event fires.

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 an X-Trxn-Signature header:
Example:

Verification steps

  1. Extract the timestamp (t) and signature (v1) from the header
  2. Check that the timestamp is within 5 minutes of the current time (prevents replay attacks)
  3. Compute the expected signature: HMAC-SHA256(secret, "<timestamp>.<raw_body>")
  4. 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

Return a 2xx response before any complex processing. Process the event asynchronously after responding to avoid timeouts.
  1. Respond quickly — return a 2xx response before any complex logic that could cause a timeout. Process the event asynchronously after responding.
  2. Handle duplicates — webhook endpoints may occasionally receive the same event more than once. Make your event processing idempotent by tracking the id from the payload.
  3. Handle out-of-order delivery — events may not arrive in chronological order. Use the timestamp field to determine the sequence rather than assuming arrival order.
  4. Always verify signatures — use the X-Trxn-Signature header to verify all incoming webhooks. Reject any webhook that fails signature verification.
  5. Use HTTPS — always use HTTPS endpoints for security.
  6. Store secrets securely — store your signing secrets in environment variables or a secrets manager, never in source code.
  7. Monitor failures — check webhook events in the dashboard to monitor delivery status.
  8. Regenerate compromised secrets — if you suspect your signing secret has been compromised, regenerate it immediately via the API.

Managing webhook endpoints

For creating, updating, deleting, and regenerating secrets for webhook endpoints, see the webhook endpoints API reference.