Webhooks

We send webhooks when a customer's balance changes due to incoming or outgoing bank-to-bank transfers, as long as a webhook URL is set—applies to both parent and sub-accounts.

Your webhook handler should respond with a 2xx status code. Otherwise the request is considered failed and will be retried with a retry policy using exponential backoff.

We use exponential backoff (factor 2.0), starting with a 1-second delay between attempts and doubling after each failure (1s → 2s → 4s → 8s, etc.). Retries continue for up to 72 hours, after which the webhook will no longer be attempted.

Outgoing Webhook Example

For example, after initiating an outgoing transfer via the API, the transfer is typically settled within a few seconds (during working hours). If a webhook URL was provided, a POST request will be sent to that endpoint as shown below:

Request:

[POST]: https://example.com/webhook-handler
Content-Type: application/json
User-Agent: PaveBank-Webhook/1.0

Body:

{
	"transaction_id": "transaction_b3mz0xppufvytxggtu7h09xb01"
}

Then call the transaction service to retrieve the complete transaction data.

For incoming transaction webhooks, you’ll get the same message, but with a different transaction_id since it's an unique for every tx.