Copy page

Webhooks

Webhooks overview

Webhooks let PayDai push events to your application the moment they happen - a sale is paid, a commission is created, a member is activated - instead of you polling our API. PayDai sends an HTTP POST with a JSON body to an endpoint URL you control.

Events are dispatched using a transactional-outbox pattern, which guarantees at-least-once delivery. That means an event may arrive more than once. Your consumer must be idempotent: de-duplicate on event_id and treat repeated deliveries as no-ops.

The envelope

Every webhook shares the same outer envelope. The entity that changed lives under data.object; the envelope around it tells you what happened and in which workspace.

Webhook envelope
{
  "event_id": "evt_2a8a4634-4223-4d19-be31-0c4ee37b71e6",
  "event_type": "sale.created",
  "api_version": "2026-06-01",
  "created_at": "2026-06-20T12:12:44.650821Z",
  "workspace_id": "ws_7c448c98-390c-4994-abe8-21d0f7b899a8",
  "livemode": false,
  "data": {
    "object": {
      "object": "sale",
      "id": "sl_6e7d79d1-3ea3-4965-95f8-8ce7f61bdb84"
    }
  }
}

Field	Type	Description
event_id	string	Unique event identifier, prefixed evt_. Use this for de-duplication.
event_type	string	The event name, e.g. sale.paid. See Event types.
api_version	string	The payload schema version, currently 2026-06-01.
created_at	datetime	ISO 8601 timestamp of when the event was emitted.
workspace_id	string	The workspace the event belongs to, prefixed ws_.
livemode	boolean	true for live data, false for test data.
data.object	object	The full entity payload. Shape depends on event_type.

Subscribe

Register a webhook endpoint from the Developer page at app.itspaydai.com/developer - enable Developer mode, then in the Webhook Endpoints section click Add Webhook and fill in the Add Webhook Endpoint form. Alternatively, create one over the API with POST /api/v1/webhook_endpoints/. When you create an endpoint you provide:

• url - the HTTPS endpoint that should receive events. PayDai will POST every selected event for your workspace to this URL.
• description - a label to identify the endpoint.
• enabled_events - the event types you want delivered to this endpoint. Pass a list of event names, or "*" to subscribe to all events.

Each endpoint also carries:

• status - one of active, disabled, or paused. Change it at any time to control whether the endpoint receives events.
• api_version - the payload schema the endpoint is pinned to. Defaults to 2026-06-01.
• custom_headers - an optional map of extra headers PayDai sends with every delivery (for example a static auth token your receiver checks). Some headers are reserved - see Custom headers.

The full list of valid event types is available from GET /api/v1/webhook_endpoints/supported-events/ (see also Event types).

For the full REST API - creating, listing, updating, deleting endpoints and revealing the signing secret - see Managing webhook endpoints.

Receiver contract

Your endpoint should:

• Respond 2xx quickly. Acknowledge receipt with any 2xx status as soon as you have safely persisted the event. Respond within ~10 seconds or the delivery is treated as failed.
• Do work asynchronously. Don't run slow business logic before responding. Persist the raw event, return 2xx, then process it in a background worker.
• Expect retries. Any non-2xx response (or a timeout) is treated as a failure and the event is retried. Combined with at-least-once delivery, this is why idempotency is required.

Delivery & retries

• At-least-once. Every event is delivered at least once, and may be delivered more than once.
• Respond fast. Return any 2xx within ~10 seconds. A 5xx, any other non-2xx, or a timeout counts as a failed delivery.
• Automatic retries. Failed deliveries are retried with exponential backoff by PayDai's delivery queue - you don't request a retry, it happens for you.
• De-duplicate on event_id. Retries reuse the same event_id. Skip any event_id you've already processed so a retried delivery is a no-op.

Verify authenticity

When you register an endpoint, PayDai returns a signing secret prefixed whsec_. The full secret is returned in the creation response - copy it and store it securely (for example, in your secrets manager). If you don't save it then, you can retrieve it again at any time with Reveal secret; everywhere else the API returns only a masked secret_hint. This secret is what your endpoint uses to verify that an inbound request genuinely came from PayDai.

Delivery headers

Every delivery includes:

Header	Description
Paydai-Signature	t=<unix_timestamp>,v1=<hex_hmac> - the timestamp and signature.
Paydai-Event-Type	The event name, e.g. sale.created.
Paydai-Api-Version	The payload schema version, e.g. 2026-06-01.
Paydai-Event-Id	The event id, matching event_id in the body.

The signature

The signature is an HMAC-SHA256:

• Key = your endpoint signing secret (whsec_...).
• Message = the string "{t}." + <raw request body>, where t is the timestamp from the header and the body is the exact raw bytes you received. Do not re-serialize the JSON - any reformatting will change the bytes and break the signature.

To verify a delivery:

1. Parse t and v1 from the Paydai-Signature header.
2. Recompute the HMAC-SHA256 over t + "." + rawBody using your signing secret.
3. Compare your computed hex digest against v1 in constant time. Reject the request if they don't match.
4. Reject the request if t is too old - recommend a tolerance of 5 minutes - to prevent replay attacks.

Verify in Node.js
const crypto = require("crypto");

function verifyPaydaiSignature(rawBody, signatureHeader, secret, toleranceSec = 300) {
  // signatureHeader: "t=<unix>,v1=<hex>"
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((kv) => kv.split("="))
  );
  const t = parts.t;
  const v1 = parts.v1;

  // Reject stale timestamps (replay protection).
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) {
    return false;
  }

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.`)
    .update(rawBody) // rawBody must be the exact raw bytes received
    .digest("hex");

  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(v1, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Verify in Python
import hashlib
import hmac
import time


def verify_paydai_signature(raw_body: bytes, signature_header: str, secret: str, tolerance_sec: int = 300) -> bool:
    # signature_header: "t=<unix>,v1=<hex>"
    parts = dict(kv.split("=", 1) for kv in signature_header.split(","))
    t, v1 = parts["t"], parts["v1"]

    # Reject stale timestamps (replay protection).
    if abs(time.time() - int(t)) > tolerance_sec:
        return False

    expected = hmac.new(
        secret.encode(),
        f"{t}.".encode() + raw_body,  # raw_body must be the exact raw bytes received
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected, v1)

This differs from request authentication. When you call the PayDai API you send your API key as a Bearer token (see Authentication). Webhook authenticity is the reverse problem - proving an inbound request really came from PayDai.

Idempotency & ordering

• De-duplicate on event_id. Store processed event_ids and skip any you've already handled. Because delivery is at-least-once, the same event can arrive multiple times.
• Don't assume ordering. Events are not guaranteed to arrive in the order they occurred. For example, sale.paid could reach you before sale.created. Reconcile state using the entity's own fields (such as status and timestamps) rather than relying on arrival order.

livemode

The livemode flag distinguishes test from live traffic:

• livemode: false - the event was generated by test data. Use this to drive your sandbox and integration tests.
• livemode: true - the event reflects real workspace activity.

Branch on livemode so test events never touch production records.

Versioning

api_version (currently 2026-06-01) identifies the schema of the payload under data.object. When PayDai makes a backwards-incompatible change to a payload, it ships under a new api_version. Pin your consumer to the version you built against and check api_version on each event so you can detect and handle upgrades deliberately.