Webhook settings

This page explains the webhook-related settings on an account. For the actual payloads Reconbanker sends, see Webhooks guide.

The webhook URL

The Webhook URL is where Reconbanker sends results. It is required on every account.

Reconbanker calls it with POST and a JSON body. The endpoint should:

• Be reachable from the public internet.
• Return a 2xx status code when the delivery is accepted. Any other status counts as a failure and triggers retry.
• Respond reasonably fast (a few seconds).

Auth headers

Reconbanker can authenticate with your server in two schemes:

• bearer - sends Authorization: Bearer <your-token>.
• api_key - sends Authorization: Api-Key <your-token>.

You configure this with the Webhook auth type and Webhook auth token settings. If both are left empty, Reconbanker sends the webhook without an Authorization header.

How the token is resolved

Reconbanker tries to keep configuration small by sharing the auth token between your Pending orders endpoint and your Webhook URL when they are the same.

The rule:

1. If Webhook auth token is set, use it.
2. Otherwise, fall back to Polling auth token.
3. Otherwise, send no Authorization header.

The auth type follows the same order: webhook auth type first, polling auth type as backup.

If your webhook receiver is a separate system from your pending-orders source, just fill both fields.

Extra fields

Set the Extra webhook fields setting to attach your own JSON metadata to every webhook payload Reconbanker sends. Useful when your receiver multiplexes several tenants or environments.

Example:

{ "tenant": "acme", "environment": "production" }

The following keys are reserved and cannot be overridden through extra fields: external_id, status, amount, currency, name, id, received_at. Trying to set them returns an error.

Retry behavior

When your server does not return a 2xx, Reconbanker retries three times with exponential backoff:

• Attempt 2 - 5 seconds later.
• Attempt 3 - 10 seconds later.
• Attempt 4 - 20 seconds later.

After that the delivery is marked as failed. You can replay it manually from the dashboard.

A minimal test receiver

To verify your settings before pointing them at production, you can run a tiny listener locally and use a tunnel (like ngrok) to expose it:

node -e "require('http').createServer((req,res)=>{let b='';req.on('data',c=>b+=c);req.on('end',()=>{console.log(req.method,req.url,b);res.end('ok')})}).listen(4000)"

Then trigger a delivery by pressing Resend webhook on any request in the dashboard, or by calling the resend endpoint.

See also

• Account settings
• Webhooks guide