Guides
Receive webhooks
When a payment changes state, Trevi POSTs the full payment object to your callback_url. Verify the signature and respond with HTTP 200 to acknowledge.
Signature header: X-BTPay-Signature: <hex> where <hex> = HMAC-SHA256(api_key, raw_body). Capture the raw request body before parsing JSON — re-serialising will change the bytes and break the HMAC.
Use a constant-time comparison (Node crypto.timingSafeEqual, Python hmac.compare_digest, PHP hash_equals) to defeat timing attacks.
Webhooks may be retried on non-2xx responses. Dedupe on (request_id, status) so duplicate deliveries are safe to receive.
Example
# Sample payload (POSTed to your callback_url):
# {
# "event": "payment.completed",
# "payment": {
# "request_id": "pay_abc…",
# "status": "completed",
# "amount_sats": 150000,
# …
# }
# }
# Header: X-BTPay-Signature: <hex(hmac-sha256(api_key, raw_body))>Was this page helpful?