Webhook Setup Guide

Event types and payload schemas are documented in the API Reference.

Payment intent webhooks use the same event_name values and payload shape for inbound invoices and outbound bills. The event_payload includes the payment intent's direction (0 inbound, 1 outbound) and read-only wallet_uid. Webhooks are delivered for payment intents created via the Foundation API and for those created inside Truss. See Payment intent webhooks for when each event fires.

Events

event_name	When it fires
payment_intent.paid	The payment intent is fully paid (balance_paid equals total). This happens as soon as the final payment starts, before the money arrives. If that payment is later returned (for example, it bounces), the payment intent is no longer Paid.
payment_intent.canceled	The payment intent is canceled.
payment_intent.updated	Fields such as total, addenda, note, memo, or due_date change.
payment_intent.transaction.added	A payment is added to the payment intent, for example when a customer pays an invoice.
action_request.updated	An action request is approved, rejected or fails.

No event fires when a payment intent is created. Store the uid from the create response so you can track each new invoice.

Registration

Contact Truss to register your webhook URL. Your endpoint must be HTTPS and publicly reachable. No self-service; we configure webhooks for you.

Delivery

Truss sends webhooks as POST requests with Content-Type: application/json. Deliveries are signed with X-Webhook-Signature so you can verify authenticity if a signing secret has been set up for your webhook subscriber. See Webhook Signature Verification.

Your endpoint has 30 seconds to respond to each request.

Retries. Truss makes up to 7 attempts in total: the first attempt plus 6 retries, with waits of 5, 10, 20, 40, 80 and 160 minutes between them (about 5¼ hours in all). Truss retries when your endpoint returns 408, 429, 500, 502, 503 or 504, times out, or cannot be reached.

Best Practices

• Return HTTP 200 quickly; process the payload asynchronously.
• Use event_id for idempotency (duplicate deliveries are possible).
• Validate event_name before processing.