Webhook integration

A webhook reports an account event to your receiving URL. It is a notification; verify the authoritative transaction state through GET transaction.

Configure the receiver

In Heth webhook settings, set a URL you control, configure the integration secret and enable delivery. Changing the URL changes who receives account events. Protect that endpoint and avoid redirects to untrusted recipients. Configuration requires the user's account session; an API key used for transactions is not automatically sufficient.

Process notifications safely

1. Validate the account webhook signature and replay checks described below.
2. Record the event/transaction identifier with sensitive fields redacted.
3. Make handling idempotent: duplicate or delayed delivery must not create another payment.
4. Retrieve the transaction with your own credential and reconcile its status.
5. Return the receiver response required by the configured delivery contract.

Do not treat a browser push notification as a webhook or a guarantee of delivery. This overview does not promise ordering, retry intervals or an authentication format common to every configured integration. Obtain the actual delivery contract before enabling production automation.

Account webhook delivery format

This format applies to account webhooks configured in Heth settings. Other callback integrations may use a different contract.

When a non-empty account webhook secret is configured, the request includes x-webhook-signature (hex HMAC-SHA256), x-webhook-timestamp (Unix seconds) and x-webhook-event-id. Verify the HMAC over timestamp + "." + the exact raw HTTP body bytes using the configured secret; do not parse and reserialize JSON before verification. Check the signed body timestamp matches the timestamp header, reject a clock difference above 5 minutes, compare signatures in constant time, and deduplicate by event_id. A retry retains event_id but receives a fresh timestamp/signature. Without a configured secret the signature headers can be absent; configure a secret before trusting automated delivery.

hex(HMAC-SHA256(secret, timestamp + "." + raw_body))

The envelope has event_id, timestamp, type and data. For account transaction events, data includes tx_id, txid, type, status, amount, currency and event_type. amount can be a JSON integer: use a lossless parser. A donation may add a donation object. Acknowledge a verified event with HTTP 2xx after recording it; repeated verified event_id values must not trigger the business action twice. Confirm the transaction through GET even after a valid notification.