Receiving webhooks
This guide builds a receiver for enterprise webhooks. The contract (headers, payload, retries, events) is in the Webhooks reference.
Enterprise only
Webhooks are sent for enterprise workspaces. Consumer escrows and Jasa Pembayaran orders do not send them; poll GET /v1/escrows/:id/payment-status for those.
1. Register an endpoint
An admin adds the webhook on the dashboard (Developers, then Webhooks, then Add webhook), or from a dashboard session with the API. API keys can list webhooks and read the delivery log, but cannot add, change or delete them (403 KEY_NOT_ALLOWED).
An endpoint belongs to one mode, Sandbox or Live, and only receives that mode's events. On the dashboard it is the mode you are in when you add it. With the API, send X-Enterprise-Mode: sandbox or live; without it the request acts in Live once Live is unlocked and in Sandbox before. Start with a Sandbox endpoint, then add a Live one when you go live.
curl -X POST https://api.rekberpay.com/v1/enterprise/webhooks \
-b cookies.txt \
-H "X-CSRF-Token: $CSRF_TOKEN" \
-H "X-Enterprise-Account: $WORKSPACE_ID" \
-H "X-Enterprise-Mode: sandbox" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/rekberpay/webhooks",
"events": [
"milestone.released",
"disbursement.settled",
"deal.created"
],
"description": "ERP sync"
}'const res = await fetch('https://api.rekberpay.com/v1/enterprise/webhooks', {
method: 'POST',
headers: {
Cookie: process.env.REKBERPAY_SESSION_COOKIE, // '__Host-rekber_session=...' from POST /v1/auth/login
'X-CSRF-Token': process.env.REKBERPAY_CSRF_TOKEN,
'X-Enterprise-Account': process.env.WORKSPACE_ID,
'X-Enterprise-Mode': 'sandbox',
'Content-Type': 'application/json',
},
body: JSON.stringify({
url: "https://example.com/rekberpay/webhooks",
events: [
"milestone.released",
"disbursement.settled",
"deal.created"
],
description: "ERP sync"
}),
});
const data = await res.json();import os
import requests
session = requests.Session()
# The session cookie from POST /v1/auth/login
session.cookies.set("__Host-rekber_session", os.environ["REKBERPAY_SESSION"], domain="api.rekberpay.com")
resp = session.post(
"https://api.rekberpay.com/v1/enterprise/webhooks",
headers={
"X-CSRF-Token": os.environ["REKBERPAY_CSRF_TOKEN"],
"X-Enterprise-Account": os.environ["WORKSPACE_ID"],
"X-Enterprise-Mode": "sandbox",
},
json={
"url": "https://example.com/rekberpay/webhooks",
"events": [
"milestone.released",
"disbursement.settled",
"deal.created",
],
"description": "ERP sync",
},
timeout=30,
)
print(resp.status_code, resp.json())<?php
$ch = curl_init('https://api.rekberpay.com/v1/enterprise/webhooks');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_COOKIEJAR => 'cookies.txt',
CURLOPT_COOKIEFILE => 'cookies.txt',
CURLOPT_HTTPHEADER => [
'X-CSRF-Token: ' . getenv('REKBERPAY_CSRF_TOKEN'),
'X-Enterprise-Account: ' . getenv('WORKSPACE_ID'),
'X-Enterprise-Mode: sandbox',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'url' => 'https://example.com/rekberpay/webhooks',
'events' => [
'milestone.released',
'disbursement.settled',
'deal.created',
],
'description' => 'ERP sync',
]),
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);201 Created
{
"success": true,
"data": {
"id": "7777777a-7777-4777-8777-777777777777",
"url": "https://example.com/rekberpay/webhooks",
"description": "ERP sync",
"events": [
"deal.created",
"disbursement.settled",
"milestone.released"
],
"status": "active",
"paused_reason": null,
"secret_fingerprint": "3fa1c09b",
"failure_count": 0,
"last_delivery_at": null,
"last_delivery_status": null,
"last_response_code": null,
"created_at": "2026-10-13T14:33:16.731Z",
"updated_at": "2026-10-13T14:33:16.731Z",
"livemode": false,
"secret": "whsec_Xb4nR7tK2mQ9vL1sP6wZ3yH8cJ0dF5gA2eU7iO4kN1t"
}
}livemode: false says this is a Sandbox endpoint. Copy secret into your secret store (for example REKBERPAY_WEBHOOK_SECRET). It is shown only once, and adding a webhook takes no Idempotency-Key, so if the call times out, list the webhooks before you try again. If you lose it, rotate it: Rotate secret on the webhook, or POST /v1/enterprise/webhooks/:id/rotate-secret. The old secret stops working at once, so update your receiver first or accept a short gap.
URL rules
RekberPay checks the URL when you add or change a webhook, and again before every delivery:
| Rule | Detail | Error code |
|---|---|---|
| Scheme | https:// only | WEBHOOK_URL_HTTPS_REQUIRED |
| Credentials | No user name or password in the URL | WEBHOOK_URL_URL_CREDENTIALS |
| Address | Every address the host resolves to must be public. Private ranges, loopback and link-local addresses are refused, as are localhost, *.localhost, *.internal, *.local and cloud metadata host names | WEBHOOK_URL_PRIVATE_ADDRESS, WEBHOOK_URL_HOST_DENIED |
| Port | 443, 8443, or 1024 to 65535 except common database and service ports such as 3306, 5432 and 6379 | WEBHOOK_URL_PORT_NOT_ALLOWED |
| Shape and length | A full URL of at most 500 characters | WEBHOOK_URL_INVALID_URL |
| DNS | The host must resolve | WEBHOOK_URL_DNS_FAILED |
| Redirects | Never followed. A 301 or 302 counts as a failed delivery, so give the final URL | |
| Limit | Up to 10 webhooks per mode: 10 in Sandbox and 10 in Live | WEBHOOK_LIMIT (409) |
A URL that breaks a rule answers 400 with one of those codes and a plain message. If the host later points to a private address, its deliveries fail.
What a delivery looks like
Each delivery is a POST with a JSON body and these headers:
| Header | Value |
|---|---|
Content-Type | application/json |
User-Agent | RekberPay-Webhooks/1.0 |
X-RekberPay-Event | The event name, for example milestone.released |
X-RekberPay-Delivery | The ID of this delivery. A retry has its own |
X-RekberPay-Signature | t=<unix seconds>,v1=<hex> |
RekberPay waits up to 10 seconds for your answer. Any 2xx is a success.
2. Verify the signature
Every request carries X-RekberPay-Signature: t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 with your secret over <t>.<raw body>. Verify it before you look at the body. Use the raw bytes as received: parsing the JSON and serialising it again changes the bytes and breaks the check.
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verifyRekberPaySignature(secret, header, rawBody, toleranceSeconds = 300) {
if (typeof header !== 'string') return false;
let t = null;
const signatures = [];
for (const part of header.split(',')) {
const [key, value] = part.trim().split('=');
if (key === 't' && /^\d+$/.test(value)) t = Number(value);
if (key === 'v1' && /^[0-9a-f]{64}$/.test(value)) signatures.push(value);
}
if (t === null || signatures.length === 0) return false;
if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSeconds) return false;
const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
return signatures.some((sig) => timingSafeEqual(expected, Buffer.from(sig, 'hex')));
}The tolerance stops an attacker who captured one request from replaying it later. Keep your server clock synced (NTP).
The same check in Python:
import hashlib
import hmac
import time
def verify_rekberpay_signature(secret: str, header: str, raw_body: bytes, tolerance: int = 300) -> bool:
if not header:
return False
timestamp = None
signatures = []
for part in header.split(","):
key, _, value = part.strip().partition("=")
if key == "t" and value.isdigit():
timestamp = int(value)
elif key == "v1" and len(value) == 64:
signatures.append(value)
if timestamp is None or not signatures:
return False
if abs(int(time.time()) - timestamp) > tolerance:
return False
signed = f"{timestamp}.".encode() + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return any(hmac.compare_digest(expected, sig) for sig in signatures)In Flask, read the bytes with request.get_data() before anything parses them.
And in PHP:
<?php
function verify_rekberpay_signature(string $secret, string $header, string $rawBody, int $tolerance = 300): bool
{
$timestamp = null;
$signatures = [];
foreach (explode(',', $header) as $part) {
$pieces = explode('=', trim($part), 2);
if (count($pieces) !== 2) {
continue;
}
[$key, $value] = $pieces;
if ($key === 't' && ctype_digit($value)) {
$timestamp = (int) $value;
} elseif ($key === 'v1' && preg_match('/^[0-9a-f]{64}$/', $value) === 1) {
$signatures[] = $value;
}
}
if ($timestamp === null || $signatures === []) {
return false;
}
if (abs(time() - $timestamp) > $tolerance) {
return false;
}
$expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
foreach ($signatures as $signature) {
if (hash_equals($expected, $signature)) {
return true;
}
}
return false;
}
$rawBody = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_REKBERPAY_SIGNATURE'] ?? '';
if (!verify_rekberpay_signature((string) getenv('REKBERPAY_WEBHOOK_SECRET'), $header, $rawBody)) {
http_response_code(400);
exit('bad signature');
}
http_response_code(204);In PHP use php://input, not $_POST or a decoded array. Whatever the language, compare with a constant time function (timingSafeEqual, hmac.compare_digest, hash_equals), never with ==.
A real signed delivery to test with
RekberPay's signer produced this header for the body below, with the sample secret whsec_Xb4nR7tK2mQ9vL1sP6wZ3yH8cJ0dF5gA2eU7iO4kN1t and t=1792128796. Feed both to your verifier with the clock check turned off (or a large tolerance): it must accept them, and reject them after you change one character of the body.
X-RekberPay-Signature: t=1792128796,v1=b32f73e84e4ef9f166187ed3a39e736228484698d96ef402cba064a188772a28{"id":"11111118-1111-4111-8111-111111111111","seq":140544,"event":"milestone.released","account_id":"fffffff2-ffff-4fff-8fff-ffffffffffff","entity_type":"milestone","entity_id":"fffffff4-ffff-4fff-8fff-ffffffffffff","deal_id":"eeeeeee4-eeee-4eee-8eee-eeeeeeeeeeee","amount":30000000,"summary":"Released DEAL-2026-0009 / Tooling and proof approval in 2 payouts","occurred_at":"2026-10-13T14:33:16.481Z","livemode":false,"data":{"previous":null,"next":{"status":"released"}}}The body is one line of compact JSON, exactly as it is sent. Verify the bytes you received, before any JSON parsing.
3. Answer fast, work later
Answer 2xx within 10 seconds or the attempt counts as failed and is retried. Store the event, answer, then process it in the background:
import express from 'express';
import { verifyRekberPaySignature } from './verify.js';
const app = express();
app.post('/rekberpay/webhooks', express.raw({ type: 'application/json' }), async (req, res) => {
const rawBody = req.body.toString('utf8');
const ok = verifyRekberPaySignature(
process.env.REKBERPAY_WEBHOOK_SECRET,
req.get('X-RekberPay-Signature'),
rawBody,
);
if (!ok) return res.status(400).send('bad signature');
const event = JSON.parse(rawBody);
// Insert-or-ignore on event.id makes a repeat delivery a no-op.
const isNew = await db.saveEventOnce(event.id, event);
if (isNew) await queue.add('rekberpay-event', { id: event.id });
res.status(204).end();
});express.raw keeps the body as bytes. With express.json() in front of this route the signature check fails.
4. Deduplicate on id
Delivery is at least once. The same event arrives again when your 2xx was lost in transit, when a retry overlaps a slow answer, or when someone presses Send again. Each delivery has its own X-RekberPay-Delivery, but the payload id is the same, so store processed ids with a unique key and skip repeats. (The one exception is webhook.test: its id is the delivery id.)
Skip test events in production
Every payload has livemode, the mode the event happened in. It is decided when the event happens and never changes: true for Live, false for Sandbox. A webhook endpoint belongs to one mode too, and it only receives that mode's events, so a Live endpoint never gets a Sandbox event. Point production at a Live endpoint and staging at a Sandbox one. webhook.test always carries livemode: false. Events from before the mode switch keep the value they had, and false there also marks test data from before Live was unlocked. Check it anyway, and never act on livemode: false in production:
const event = JSON.parse(rawBody);
if (process.env.NODE_ENV === 'production' && event.livemode !== true) {
return res.status(204).end();
}5. Order by seq
Deliveries can arrive out of order (a retry of an older event can land after a newer one). Each payload has seq, the same increasing number as GET /v1/enterprise/events. If you keep state per deal or milestone, ignore an event whose seq is lower than the last one you applied for that entity, or read the current state from the API before acting.
6. Recover from downtime
- A failed attempt is retried after 10s, 20s, 30s, 45s and 60s, then 2m, 2m, 2.5m, 3m and 3m (about 15 minutes in all), then every hour until 24 hours after the first attempt (34 attempts at most), each delay with about 10% random jitter. After that the delivery is marked
failed. A failed delivery stays in the event feed, and Send again still works on it. - The webhook is paused only after 20 failed attempts in a row whose failing streak began at least 1 hour earlier. While it is paused, deliveries already queued for it stay
pending, and all of them go out once you resume it. Resume it on the dashboard. - To fill a gap, page
GET /v1/enterprise/events?after=<last seq you processed>. It returns the same events, including ones a paused webhook never sent. - To send a single delivery again, open the webhook on the dashboard and press Send again on that delivery (or use the API call in Manage a webhook).
The delivery log is readable with a workspace key:
curl "https://api.rekberpay.com/v1/enterprise/webhooks/7777777a-7777-4777-8777-777777777777/deliveries?limit=5" \
-H "Authorization: Bearer $REKBERPAY_WORKSPACE_KEY"const res = await fetch('https://api.rekberpay.com/v1/enterprise/webhooks/7777777a-7777-4777-8777-777777777777/deliveries?limit=5', {
headers: {
Authorization: `Bearer ${process.env.REKBERPAY_WORKSPACE_KEY}`,
},
});
const data = await res.json();import os
import requests
resp = requests.get(
"https://api.rekberpay.com/v1/enterprise/webhooks/7777777a-7777-4777-8777-777777777777/deliveries?limit=5",
headers={
"Authorization": f"Bearer {os.environ['REKBERPAY_WORKSPACE_KEY']}",
},
timeout=30,
)
print(resp.status_code, resp.json())<?php
$ch = curl_init('https://api.rekberpay.com/v1/enterprise/webhooks/7777777a-7777-4777-8777-777777777777/deliveries?limit=5');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('REKBERPAY_WORKSPACE_KEY'),
],
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);200 OK
{
"success": true,
"data": [
{
"id": "9999999a-9999-4999-8999-999999999999",
"event": "webhook.test",
"event_seq": null,
"status": "pending",
"attempts": 0,
"next_attempt_at": "2026-10-13T14:33:16.747Z",
"response_code": null,
"response_body": null,
"last_error": null,
"duration_ms": null,
"delivered_at": null,
"created_at": "2026-10-13T14:33:16.747Z"
}
],
"pagination": {
"page": 1,
"limit": 5,
"total": 1,
"total_pages": 1
}
}7. Test it
- Send test on the dashboard queues a
webhook.testevent withseq: null. It goes out within about 30 seconds and shows in the delivery log with your status code and the first 500 characters of your answer. - In Sandbox, with a Sandbox endpoint, fund and release a milestone to get real
milestone.fundedandmilestone.releaseddeliveries. No real money moves. - Your endpoint must be reachable from the internet over https. For local development, expose your server with a tunnel that gives you a public https URL.
Events you can subscribe to
When you add a webhook you choose events, or * for all of them. The groups below match the dashboard picker. The Webhooks reference has the full, current list and the payload of each.
| Group | Events |
|---|---|
| Deals | deal.created, deal.updated, deal.activated, deal.cancelled, deal.funded, deal.fee_proposed, deal.fee_agreed |
| Milestones | milestone.added, milestone.updated, milestone.funded, milestone.evidence_submitted, milestone.revision_requested, milestone.approved, milestone.released, milestone.paid, milestone.shipped, milestone.received, milestone.release_pending, milestone.auto_released, milestone.auto_refunded, milestone.release_reversed, milestone.extended |
| Approvals | approval.requested, approval.decided |
| Disputes | dispute.opened, dispute.evidence_added, dispute.resolved |
| Payouts | disbursement.queued, disbursement.requeued, disbursement.processing, disbursement.settled, disbursement.failed, payout_instruction.created, payout_instruction.updated, payout_instruction.deleted, payout_instruction.verified, payout_instruction.suspended |
| Refunds | refund.queued, refund.requeued, refund.processing, refund.settled, refund.failed |
| Counterparties | counterparty.created, counterparty.updated, counterparty.kyb_updated, counterparty.link_requested, counterparty.linked, counterparty.link_declined, counterparty.unlinked |
| Documents | document.added, document.deleted |
| Platform mode only | platform.user.linked, platform.user.consent_declined, platform.user.claimed, platform.user.unlinked, platform.user.kyc_updated, platform.user.balance_scope_changed, platform.user.deletion_requested, platform.user.deletion_cancelled, platform.user.deleted, bank_account.added, withdrawal.requested, withdrawal.settled, withdrawal.failed, withdrawal.returned, deposit.required, deposit.paid, deposit.applied, deposit.returned |
| Ratings | rating.created, rating.published, rating.hidden |
| Chat | message.created |
| Workspace | account.created, account.updated, settings.updated, member.added, member.invited, member.joined, member.removed, member.role_changed, webhook.paused |
Most integrations need only a few: milestone.funded to start work, milestone.evidence_submitted and milestone.approved to follow the review, disbursement.settled and disbursement.failed to reconcile payouts, and dispute.opened and dispute.resolved. The Refunds group reports the money going back to the payer after a dispute cancels a milestone or a funded deal is cancelled. See Refunds on a workspace deal.
The Platform mode events, the eight milestone.* events from milestone.paid on the rating.* events, message.created and the four deposit.* events come only from Platform mode (PaaS) activity, so a workspace that does not use Platform never receives them. That makes 30 new events in all. They name users by your partner_user_ref; the Platform reference says when each one fires and lists the fields of each payload.
A webhook subscribed to * now also receives dispute.evidence_added (a statement and files added to a dispute, on regular enterprise deals too) and, in a workspace with Platform mode, the Platform events. Answer 2xx to events you do not know, and ignore keys you do not know. If you handle only some events, subscribe to those by name instead of *.
deal.fee_proposed and deal.fee_agreed are written to the paying workspace's feed. The counterparty.link_requested, counterparty.linked, counterparty.link_declined and counterparty.unlinked events are written to the feed of each workspace in the link. Changes to the webhooks themselves are never sent, except webhook.paused, which is sent so a second endpoint can warn you.
Manage a webhook
| Action | Dashboard | API (dashboard session, admin) |
|---|---|---|
| Add | Add webhook | POST /v1/enterprise/webhooks |
| Change URL, events or description | Open the webhook | PATCH /v1/enterprise/webhooks/:id |
| Pause or resume | Pause, Resume | PATCH with "status": "paused" or "active" |
| Send a test | Send test | POST /v1/enterprise/webhooks/:id/test |
| Send one delivery again | Send again | POST /v1/enterprise/webhooks/:id/deliveries/:did/redeliver |
| Rotate the secret | Rotate secret | POST /v1/enterprise/webhooks/:id/rotate-secret |
| Delete | Delete webhook | DELETE /v1/enterprise/webhooks/:id |
Resuming a paused webhook resets its failure count. A test or a resend on a paused webhook answers 409 WEBHOOK_PAUSED.
Read the delivery log
Open the webhook in the dashboard, or call GET /v1/enterprise/webhooks/:id/deliveries (any member, and workspace keys too). It lists the newest deliveries first, 20 a page and up to 50 with limit. Delivered rows are kept 30 days and failed rows 90 days.
| Field | What it tells you |
|---|---|
event, event_seq | The event and its seq (null for webhook.test) |
status | pending (waiting for its next try, or queued on a paused webhook until you resume it), delivered or failed (out of retries after 24 hours, or the webhook was disabled) |
attempts, next_attempt_at | Tries so far, and when the next one goes out while pending |
response_code, response_body | What your server answered, the body cut to its first 500 characters |
last_error | Why the last try failed when there was no answer, for example a timeout or Webhook disabled |
duration_ms, delivered_at | How long your server took, and when it accepted the delivery |
Send again (POST /v1/enterprise/webhooks/:id/deliveries/:did/redeliver) queues a new delivery of the same event with a new X-RekberPay-Delivery ID and a fresh signature. The payload id of a real event stays the same, so your deduplication still works (a webhook.test gets a new one). It answers 202 with the new delivery_id.
When RekberPay pauses a webhook
Each failed attempt (no answer within 10 seconds, or anything but a 2xx) adds one to the webhook's failure_count, and any delivered attempt sets it back to 0. RekberPay pauses the webhook when both hold: 20 failed attempts in a row, and the streak of failures began at least 1 hour ago. A short outage on a busy workspace therefore never pauses it. When it pauses:
statusbecomespausedwithpaused_reason: "failures"(a pause you make yourself readsmanual);- its deliveries that were already queued stay
pending: nothing is cancelled, and they wait while the webhook is paused. Events that happen while it is paused are not queued for it; - a
webhook.pausedevent is recorded and sent to your other active webhooks, so a second endpoint can raise the alarm.
To recover, fix the endpoint, choose Resume (or PATCH with "status": "active"), press Send test to check it, then fill the gap from the event feed with GET /v1/enterprise/events?after=<last seq you processed>. On resume, every delivery that was queued before the pause goes out again. Events that happened while the webhook was paused are not sent on their own: read them from the event feed.
Checklist
- Verify
X-RekberPay-Signatureon the raw body, with a 5 minute tolerance. - Answer
2xxwithin 10 seconds; do the work in a queue. - Deduplicate on the payload
id. - In production, ignore events with
livemode: false. - Use
seq(or a fresh API read) before applying state changes. - Watch the webhook's status; resume it after fixing an outage and backfill from the events feed.