Skip to content

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.

bash
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"
  }'
js
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();
python
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
<?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

json
{
    "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:

RuleDetailError code
Schemehttps:// onlyWEBHOOK_URL_HTTPS_REQUIRED
CredentialsNo user name or password in the URLWEBHOOK_URL_URL_CREDENTIALS
AddressEvery 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 namesWEBHOOK_URL_PRIVATE_ADDRESS, WEBHOOK_URL_HOST_DENIED
Port443, 8443, or 1024 to 65535 except common database and service ports such as 3306, 5432 and 6379WEBHOOK_URL_PORT_NOT_ALLOWED
Shape and lengthA full URL of at most 500 charactersWEBHOOK_URL_INVALID_URL
DNSThe host must resolveWEBHOOK_URL_DNS_FAILED
RedirectsNever followed. A 301 or 302 counts as a failed delivery, so give the final URL
LimitUp to 10 webhooks per mode: 10 in Sandbox and 10 in LiveWEBHOOK_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:

HeaderValue
Content-Typeapplication/json
User-AgentRekberPay-Webhooks/1.0
X-RekberPay-EventThe event name, for example milestone.released
X-RekberPay-DeliveryThe ID of this delivery. A retry has its own
X-RekberPay-Signaturet=<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.

js
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:

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
<?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.

text
X-RekberPay-Signature: t=1792128796,v1=b32f73e84e4ef9f166187ed3a39e736228484698d96ef402cba064a188772a28
text
{"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:

js
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:

js
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:

bash
curl "https://api.rekberpay.com/v1/enterprise/webhooks/7777777a-7777-4777-8777-777777777777/deliveries?limit=5" \
  -H "Authorization: Bearer $REKBERPAY_WORKSPACE_KEY"
js
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();
python
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
<?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

json
{
    "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.test event with seq: 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.funded and milestone.released deliveries. 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.

GroupEvents
Dealsdeal.created, deal.updated, deal.activated, deal.cancelled, deal.funded, deal.fee_proposed, deal.fee_agreed
Milestonesmilestone.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
Approvalsapproval.requested, approval.decided
Disputesdispute.opened, dispute.evidence_added, dispute.resolved
Payoutsdisbursement.queued, disbursement.requeued, disbursement.processing, disbursement.settled, disbursement.failed, payout_instruction.created, payout_instruction.updated, payout_instruction.deleted, payout_instruction.verified, payout_instruction.suspended
Refundsrefund.queued, refund.requeued, refund.processing, refund.settled, refund.failed
Counterpartiescounterparty.created, counterparty.updated, counterparty.kyb_updated, counterparty.link_requested, counterparty.linked, counterparty.link_declined, counterparty.unlinked
Documentsdocument.added, document.deleted
Platform mode onlyplatform.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
Ratingsrating.created, rating.published, rating.hidden
Chatmessage.created
Workspaceaccount.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 ​

ActionDashboardAPI (dashboard session, admin)
AddAdd webhookPOST /v1/enterprise/webhooks
Change URL, events or descriptionOpen the webhookPATCH /v1/enterprise/webhooks/:id
Pause or resumePause, ResumePATCH with "status": "paused" or "active"
Send a testSend testPOST /v1/enterprise/webhooks/:id/test
Send one delivery againSend againPOST /v1/enterprise/webhooks/:id/deliveries/:did/redeliver
Rotate the secretRotate secretPOST /v1/enterprise/webhooks/:id/rotate-secret
DeleteDelete webhookDELETE /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.

FieldWhat it tells you
event, event_seqThe event and its seq (null for webhook.test)
statuspending (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_atTries so far, and when the next one goes out while pending
response_code, response_bodyWhat your server answered, the body cut to its first 500 characters
last_errorWhy the last try failed when there was no answer, for example a timeout or Webhook disabled
duration_ms, delivered_atHow 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:

  • status becomes paused with paused_reason: "failures" (a pause you make yourself reads manual);
  • 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.paused event 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-Signature on the raw body, with a 5 minute tolerance.
  • Answer 2xx within 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.

Escrow, payment services and B2B deals for Indonesian businesses.