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.

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. We allow 30 seconds per request and retry up to 7 times with exponential backoff. Retries occur on 5xx, 408, 429, and transient connection errors.

Best Practices

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