Webhook

This guide is for partners who registered on partners.rozo.ai and want to receive payment notifications in their own backend.

You configure your webhook URL once in the dashboard. From then on, every payment created under your appId automatically uses that URL and the long-lived HMAC secret you got at registration — you never pass webhookUrl or webhookSecret on individual payment requests.

---

1. Concepts

Term	Meaning
appId	Your account identifier. Derived from your slug at registration: merchant_<slug> or wallet_<slug>
Webhook URL	The HTTPS endpoint Rozo POSTs payment events to
Webhook secret	A 64-character hex string used to sign every webhook to your URL. Generated by Rozo at registration, rotatable from the dashboard
Fingerprint	sha256(secret) (hex). Shown in the dashboard so you can confirm which secret your server is currently using without exposing the raw value

The raw secret is shown to you once — at registration and again when you rotate. After that, only the fingerprint is visible.

---

2. Get Your Webhook Secret

At registration

When you complete registration on partners.rozo.ai, the response includes:

{
  "developerId": "...",
  "appId": "merchant_hellocafe",
  "webhookUrl": "https://hellocafe.com/rozo/webhook",
  "webhookSecret": "a1b2c3d4...64-hex-chars",
  "webhookSecretFingerprint": "sha256:abcd1234...full-hex"
}

Copy the webhookSecret immediately. It is not shown again.

If you lost it — rotate

1. Sign in to partners.rozo.ai.

2. Open Settings → Webhooks.

3. Click Rotate secret and confirm.

4. Copy the new secret. The old one stops working immediately — there is no grace period.

The dashboard always shows the fingerprint of the active secret and the timestamp of the last rotation, so you can confirm at a glance which version your server is configured for.

---

3. Set or Update Your Webhook URL

Either at registration (the webhookUrl field on POST /merchant-api/register) or later from Settings → Webhooks.

Requirements:

• Must start with https:// (HTTP is rejected).

• Must be reachable from the public internet.

• Should return a 2xx response quickly. If your processing is slow, return 200 immediately and process asynchronously.

You can change the URL at any time without rotating the secret. The change applies to new payment events; in-flight events for already-completed payments are not re-delivered, and pre-existing payments retain whatever URL was active when they were created.

---

4. What Triggers a Webhook

Rozo sends two webhook events per payment, both with the envelope described in §5:

Event type	Trigger
payment_payin_completed	Buyer's payin tx confirmed on the source chain
payment_payout_completed	Payout tx confirmed on the destination chain (terminal success)

Failure terminals (payment_bounced / payment_expired / payment_refunded) and intermediate states (payment_started, payment_bridging, payment_payout_started) do not generate a webhook. Your server must poll GET /payment-api/payments/{id} to observe those.

Failure handling is on you. Schedule a periodic GET /payment-api/payments/{id} for any payment that hasn't reached a success terminal within your expected window — see §7 Delivery Semantics.

---

5. Request Format

Rozo sends a POST request with these headers:

Content-Type: application/json
X-Rozo-Timestamp: 1746282100000
X-Rozo-Signature: sha256=a1b2c3d4...

Header	Description
X-Rozo-Timestamp	Unix timestamp in milliseconds when Rozo signed the request
X-Rozo-Signature	sha256= followed by the HMAC-SHA256 hex signature

Body

The body is a small envelope wrapped around the same Payment object you get from GET /payment-api/payments/{id}. Reconciliation against your stored order is a key-by-key compare on data.

{
  "event_id": "9d4f2e0c-7a55-4b1b-8e2a-6c1f0a5d8e30",
  "type": "payment_payout_completed",
  "timestamp": "2026-05-08T12:34:32.501Z",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "appId": "merchant_hellocafe",
    "orderId": "order-2026-1042",
    "status": "payment_payout_completed",
    "type": "exactIn",
    "createdAt": "2026-05-08T12:30:00.000Z",
    "updatedAt": "2026-05-08T12:34:32.000Z",
    "expiresAt": "2026-05-08T13:00:00.000Z",
    "display": {
      "title": "Order #1042",
      "description": "Coffee + pastry",
      "currency": "USD"
    },
    "source": {
      "chainId": "8453",
      "tokenSymbol": "USDC",
      "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "10.00",
      "receiverAddress": "0xForwarderAddressOnBase...",
      "fee": "0.05",
      "senderAddress": "0x1234567890123456789012345678901234567890",
      "txHash": "0xabcd1234...",
      "amountReceived": "10.00",
      "confirmedAt": "2026-05-08T12:31:55.000Z"
    },
    "destination": {
      "chainId": "1500",
      "receiverAddress": "GMERCHANTSTELLARWALLET...",
      "tokenSymbol": "USDC",
      "tokenAddress": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "amount": "9.95",
      "txHash": "3YgVxWDRKtWnzKNnXR6...",
      "confirmedAt": "2026-05-08T12:34:30.000Z"
    }
  }
}

Envelope fields

Field	Notes
event_id	Globally unique delivery id. Use this as your idempotency key. Equal to the deliveryId shown in the dashboard's delivery log — paste it there to find the matching record
type	payment_payin_completed or payment_payout_completed (see §4)
timestamp	ISO-8601 (UTC) when Rozo emitted this event
data	The Payment object, identical to GET /payment-api/payments/{data.id} (with the fields below stripped)

Fields stripped from data

These are omitted from webhook payloads even though they appear on GET /payment-api/payments/{id}:

• metadata — internal channel only.

• webhookUrl, webhookSecretSource — self-referential.

• paymentLink — you generated this flow; you don't need the link.

• merchant — branding fields you already configured.

If you need any of the above, fetch them via GET /payment-api/payments/{data.id}.

Field presence by type

data always carries the full Payment schema — fields that haven't been populated yet are sent as null, never omitted. This matches the shape GET /payment-api/payments/{id} returns, so reconcile logic can be byte-for-byte identical.

Field	payment_payin_completed	payment_payout_completed
data.source.txHash	populated	populated
data.source.senderAddress	populated	populated
data.source.amountReceived	populated	populated
data.source.confirmedAt	populated	populated
data.destination.txHash	null	populated
data.destination.confirmedAt	null	populated

Concrete payload examples

payment_payin_completed for a wallet_* account (destination tx not yet known):

{
  "event_id": "f1a8c0e2-2d36-4b87-9b2f-0a7c3e91d24e",
  "type": "payment_payin_completed",
  "timestamp": "2026-05-10T14:44:55.075Z",
  "data": {
    "id": "a22a0213-9b4e-4113-adef-acdf958a84ae",
    "appId": "wallet_hellotest",
    "orderId": null,
    "status": "payment_payin_completed",
    "type": "exactIn",
    "createdAt": "2026-05-10T14:42:00.000Z",
    "updatedAt": "2026-05-10T14:44:55.000Z",
    "display": {
      "title": "Test payment",
      "currency": "USD"
    },
    "source": {
      "chainId": "8453",
      "tokenSymbol": "USDC",
      "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "10.00",
      "receiverAddress": "0xForwarderAddressOnBase...",
      "fee": "0.05",
      "senderAddress": "0x5772fbe7a7817ef7f586215ca8b23b8dd22c8897",
      "txHash": "0x76d360eb2ef590390e36533455da2db9f19cb2463275d93fa791cd6a3e965e5b",
      "amountReceived": "10.00",
      "confirmedAt": "2026-05-10T14:44:50.000Z"
    },
    "destination": {
      "chainId": "1500",
      "receiverAddress": "GUSERSTELLARWALLET...",
      "receiverMemo": null,
      "tokenSymbol": "USDC",
      "tokenAddress": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "amount": "9.95",
      "txHash": null,
      "confirmedAt": null
    }
  }
}

payment_payout_completed for the same payment (now with destination.txHash and destination.confirmedAt populated):

{
  "event_id": "9d4f2e0c-7a55-4b1b-8e2a-6c1f0a5d8e30",
  "type": "payment_payout_completed",
  "timestamp": "2026-05-10T14:45:09.501Z",
  "data": {
    "id": "a22a0213-9b4e-4113-adef-acdf958a84ae",
    "appId": "wallet_hellotest",
    "orderId": null,
    "status": "payment_payout_completed",
    "type": "exactIn",
    "createdAt": "2026-05-10T14:42:00.000Z",
    "updatedAt": "2026-05-10T14:45:09.000Z",
    "display": {
      "title": "Test payment",
      "currency": "USD"
    },
    "source": {
      "chainId": "8453",
      "tokenSymbol": "USDC",
      "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "10.00",
      "receiverAddress": "0xForwarderAddressOnBase...",
      "fee": "0.05",
      "senderAddress": "0x5772fbe7a7817ef7f586215ca8b23b8dd22c8897",
      "txHash": "0x76d360eb2ef590390e36533455da2db9f19cb2463275d93fa791cd6a3e965e5b",
      "amountReceived": "10.00",
      "confirmedAt": "2026-05-10T14:44:50.000Z"
    },
    "destination": {
      "chainId": "1500",
      "receiverAddress": "GUSERSTELLARWALLET...",
      "tokenSymbol": "USDC",
      "tokenAddress": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "amount": "9.95",
      "txHash": "3YgVxWDRKtWnzKNnXR6pqghBSTCBA8axpPHjApmyNZTvhqUShohfDRpv7FaEGjh48WyrEfxrGxZxJ6E2mNJQtV8u",
      "confirmedAt": "2026-05-10T14:45:08.000Z"
    }
  }
}

---

6. Verify the Signature

Algorithm: HMAC-SHA256 Message: ${X-Rozo-Timestamp}.${raw request body} Header: X-Rozo-Signature: sha256=<hex>

Always:

1. Confirm the timestamp is within 5 minutes of your server clock (replay protection).

2. Compute the HMAC over timestamp + "." + raw_body using your webhook secret.

3. Compare with constant-time equality. Never use === on signature strings.

4. Use the raw body bytes — do not parse and re-serialize the JSON before signing.

Node.js / TypeScript

import crypto from 'crypto';
import express from 'express';

const app = express();

app.post(
  '/webhooks/rozo',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const timestamp = req.headers['x-rozo-timestamp'] as string;
    const sigHeader = req.headers['x-rozo-signature'] as string;
    const rawBody = req.body.toString('utf8');
    const secret = process.env.ROZO_WEBHOOK_SECRET!;

    // 1. Replay window
    if (Math.abs(Date.now() - parseInt(timestamp, 10)) > 5 * 60 * 1000) {
      return res.status(401).json({ error: 'timestamp_expired' });
    }

    // 2. Recompute signature
    const expected = crypto
      .createHmac('sha256', secret)
      .update(`${timestamp}.${rawBody}`)
      .digest('hex');

    // 3. Constant-time compare. The header may be "sha256=<hex>" or "<hex>".
    const received = sigHeader.replace(/^sha256=/, '');
    const ok = crypto.timingSafeEqual(
      Buffer.from(expected, 'hex'),
      Buffer.from(received, 'hex'),
    );
    if (!ok) return res.status(401).json({ error: 'invalid_signature' });

    // 4. Idempotency: event_id is globally unique per delivery.
    const event = JSON.parse(rawBody);
    if (await db.alreadyProcessed(event.event_id)) {
      return res.json({ ok: true });
    }

    // 5. Business logic. event.data is the same Payment object as
    //    GET /payment-api/payments/{id}.
    if (event.type === 'payment_payout_completed') {
      await fulfillOrder(event.data.id, event.data.destination.txHash);
    }

    await db.markProcessed(event.event_id);
    res.json({ ok: true });
  },
);

Python (Flask)

import hmac, hashlib, time, json, os
from flask import Flask, request, jsonify

app = Flask(__name__)
SECRET = os.environ['ROZO_WEBHOOK_SECRET']

@app.post('/webhooks/rozo')
def rozo_webhook():
    ts = request.headers.get('X-Rozo-Timestamp', '')
    sig = request.headers.get('X-Rozo-Signature', '')
    raw = request.get_data(as_text=True)

    if abs(int(time.time() * 1000) - int(ts)) > 5 * 60 * 1000:
        return jsonify(error='timestamp_expired'), 401

    expected = hmac.new(SECRET.encode(), f'{ts}.{raw}'.encode(), hashlib.sha256).hexdigest()
    received = sig.removeprefix('sha256=')
    if not hmac.compare_digest(expected, received):
        return jsonify(error='invalid_signature'), 401

    event = json.loads(raw)
    if db.already_processed(event['event_id']):
        return jsonify(ok=True)

    # event['data'] is the same Payment object as GET /payment-api/payments/{id}
    if event['type'] == 'payment_payout_completed':
        fulfill_order(event['data']['id'], event['data']['destination']['txHash'])

    db.mark_processed(event['event_id'])
    return jsonify(ok=True)

Go

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "encoding/json"
    "io"
    "net/http"
    "os"
    "strconv"
    "strings"
    "time"
)

func handle(w http.ResponseWriter, r *http.Request) {
    ts := r.Header.Get("X-Rozo-Timestamp")
    sigHdr := r.Header.Get("X-Rozo-Signature")
    raw, _ := io.ReadAll(r.Body)
    secret := os.Getenv("ROZO_WEBHOOK_SECRET")

    n, _ := strconv.ParseInt(ts, 10, 64)
    if abs(time.Now().UnixMilli()-n) > 5*60*1000 {
        http.Error(w, `{"error":"timestamp_expired"}`, 401)
        return
    }

    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(ts + "." + string(raw)))
    expected := hex.EncodeToString(mac.Sum(nil))
    received := strings.TrimPrefix(sigHdr, "sha256=")
    if !hmac.Equal([]byte(expected), []byte(received)) {
        http.Error(w, `{"error":"invalid_signature"}`, 401)
        return
    }

    var ev map[string]any
    json.Unmarshal(raw, &ev)
    // dedupe on ev["event_id"]; payment fields are under ev["data"].
    w.Write([]byte(`{"ok":true}`))
}

func abs(x int64) int64 { if x < 0 { return -x }; return x }

---

7. Delivery Semantics — Read This Carefully

Rozo webhooks are at-most-once delivery. This is a design choice, not a gap.

Question	Answer
How many times is each event delivered?	At most once. No retries. Whether your server returns 2xx, 5xx, or times out, Rozo will not re-send the same event
What happens on failure?	The delivery is recorded in the dashboard log as exhausted. Reconciliation is on you — call GET /payment-api/payments/{id} to check the current status
Are deliveries ordered?	Best-effort by event time. Do not rely on strict ordering — your handler should tolerate payment_payout_completed arriving before payment_payin_completed
Are deliveries deduplicated?	One POST per delivery, identified by event_id. Dedupe on event_id to be safe against your own proxies / framework retries
How do I dedupe?	Use event_id as the idempotency key. It is a UUID, globally unique, and equal to the deliveryId shown in the dashboard delivery log
Will I get an email if a delivery fails?	No. Use the dashboard delivery log + your own monitoring

Practical implication: for any payment your business cares about, don't rely on the webhook alone. Your server should also poll GET /payment-api/payments/{id} (or /payments/order/{appId}/{orderId}) periodically until you observe a terminal status. The webhook is a fast-path optimization on top of polling — it saves you a poll, but it isn't the source of truth, and it does not fire on failure terminals.

---

8. Inspect Deliveries in the Dashboard

Settings → Webhooks → Recent deliveries shows every POST Rozo has tried to send to your URL. Each row contains:

• deliveryId — UUID of this delivery, equal to the event_id on the webhook body. If you store event_id in your handler, paste it here to find the matching record

• paymentId — the order it relates to

• eventType — the event that triggered the delivery (payment_payin_completed or payment_payout_completed)

• statusCode — HTTP status your endpoint returned

• responsePreview — first 200 chars of your response body

• deliveredAt — when Rozo POSTed

• status — delivered (2xx) or exhausted (anything else)

attemptNumber is always 1 (at-most-once delivery — no retries by design).

You can also fetch this programmatically:

curl -H "Authorization: Bearer $JWT" \
  "https://aozudqtlykbhzbuzalzz.supabase.co/functions/v1/merchant-api/me/webhook/deliveries?limit=50"

---

9. Test Your Endpoint

a. Expose your localhost

ngrok http 3000
# → https://abc123.ngrok.io

Set https://abc123.ngrok.io/webhooks/rozo as your webhook URL in the dashboard.

b. Send a signed test event

#!/usr/bin/env bash
SECRET="paste-your-64-hex-secret-here"
URL="https://abc123.ngrok.io/webhooks/rozo"
TIMESTAMP=$(date +%s%3N)

# Body must be a single canonical JSON string — sign exactly the bytes you POST.
BODY='{"event_id":"00000000-0000-0000-0000-000000000001","type":"payment_payout_completed","timestamp":"2026-05-09T00:00:00.000Z","data":{"id":"test-payment-id","appId":"merchant_hellocafe","status":"payment_payout_completed","source":{"senderAddress":"0x1111","txHash":"0xaaaa","amountReceived":"10.00"},"destination":{"txHash":"0xbbbb","confirmedAt":"2026-05-09T00:00:00.000Z"}}}'

SIG=$(printf '%s' "${TIMESTAMP}.${BODY}" \
  | openssl dgst -sha256 -hmac "$SECRET" \
  | awk '{print $2}')

curl -X POST "$URL" \
  -H "Content-Type: application/json" \
  -H "X-Rozo-Timestamp: $TIMESTAMP" \
  -H "X-Rozo-Signature: sha256=$SIG" \
  --data-binary "$BODY" -i

Your server should respond with 200.

c. Negative tests

• Wrong signature — replace the hex with garbage. Expect 401.

• Stale timestamp — set TIMESTAMP=$(( $(date +%s%3N) - 400000 )). Expect 401.

• Replayed (id, status) — send the same body twice. Expect both 200, but business logic runs only once.

d. End-to-end with a real payment

Create a small live payment for your appId (any valid POST /payment-api/payments call where the appId is yours), pay it on-chain, and watch the dashboard delivery log + your own server logs.

You should observe two deliveries to your URL: one payment_payin_completed after the buyer's payin lands, then one payment_payout_completed after the destination payout confirms.

---

10. Identifying Which Secret Is Active

The dashboard shows the fingerprint of the active secret — a SHA-256 hash of the plaintext, displayed as sha256:<64 hex chars>. To confirm your server is using the right secret, compute the fingerprint locally:

printf '%s' "$ROZO_WEBHOOK_SECRET" | openssl dgst -sha256 | awk '{print $2}'

Compare with the value shown in Settings → Webhooks. They must match.

Note: the dashboard exposes the full fingerprint as the canonical identifier — there is no short alias (e.g. whsec_••••abcd) by design. If you want a compact tag for your own logs, use the first 8 hex chars of the fingerprint — it's stable until the next rotation.

After rotating, the fingerprint changes; webhookSecretRotatedAt is also updated so you can audit when the change happened.

---

11. Security Checklist

• Secret stored in environment variable / secrets manager — never in code.

• Signature verified on every request before any side effects.

• Timestamp checked — reject anything more than 5 minutes off.

• Constant-time signature comparison.

• Raw request bytes used for signing (no re-serialize).

• Idempotent on event_id.

• HTTPS enforced on your endpoint (HTTP refused at registration anyway).

• Reconciliation job that polls GET /payments/{id} for any payment without a terminal webhook within an expected window — webhook is at-most-once and doesn't fire on failures.

---

12. Related

• Dashboard: partners.rozo.ai/settings/webhooks