Webhook Events

SohoPay delivers webhooks as POST requests with a JSON body whenever a resource changes state. This page is the event catalog plus the delivery contract — payloads, signatures, retries, and deduplication. For registering endpoints and operational setup, see the webhooks guide.

Event envelope

Every delivery uses the same envelope; the event-specific object lives under data, and the globally unique event_id is your deduplication key (see below):

{
  "event_id": "evt_9c8b7a6d5e4f",
  "type": "payment.settled",
  "created_at": "2026-08-22T10:16:02Z",
  "data": { "...": "..." }
}

Event types by resource

Payment events

Type	Fired when
`payment.created`	An agent submitted a payment and it entered Policy Service checks
`payment.settled`	The payment settled on-chain; the merchant has been paid
`payment.failed`	The payment was declined (credit, allowlist, AML) or settlement failed

payment.settled

{
  "event_id": "evt_9c8b7a6d5e4f",
  "type": "payment.settled",
  "created_at": "2026-08-22T10:16:02Z",
  "data": {
    "payment_id": "pay_5c4b3a29",
    "order_id": "ord_9f8e7d6c",
    "agent_id": "agt_7d1e5b2f",
    "merchant_id": "mch_1a2b3c4d",
    "amount": "1.00",
    "status": "settled",
    "settlement_tx": "0x4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c9a0b",
    "settled_at": "2026-08-22T10:16:02Z"
  }
}

Settlement events

Type	Fired when
`settlement.initiated`	An on-chain settlement transaction was submitted
`settlement.completed`	The settlement confirmed on-chain
`settlement.failed`	The settlement transaction failed or was rejected

settlement.completed

{
  "event_id": "evt_2f3e4d5c6b7a",
  "type": "settlement.completed",
  "created_at": "2026-08-22T10:16:03Z",
  "data": {
    "settlement_id": "stl_8e7f6a5b",
    "payment_id": "pay_5c4b3a29",
    "merchant_id": "mch_1a2b3c4d",
    "gross_amount": "1.00",
    "merchant_amount": "1.00",
    "fee_amount": "0.05",
    "tx_hash": "0x4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c9a0b",
    "completed_at": "2026-08-22T10:16:03Z"
  }
}

merchant_amount always equals gross_amount — the 5% fee is charged to the operator’s credit line, never deducted from the merchant. See Fees.

Agent events

Type	Fired when
`agent.created`	A new agent wallet and credit line were provisioned
`agent.key_rotated`	The agent’s MPC key share was rotated
`agent.aml_review`	AML screening flagged the agent’s wallet for manual review
`agent.aml_declined`	AML screening declined the wallet; the agent cannot transact

agent.aml_declined

{
  "event_id": "evt_6a5b4c3d2e1f",
  "type": "agent.aml_declined",
  "created_at": "2026-08-22T11:42:17Z",
  "data": {
    "agent_id": "agt_3c2d1e0f",
    "merchant_id": "mch_1a2b3c4d",
    "wallet_address": "0x1f2e3d4c5b6a79880716253449586a7b8c9d0e1f",
    "screening_result": "declined",
    "flags": ["sanctions_exposure"],
    "declined_at": "2026-08-22T11:42:17Z"
  }
}

Treat agent.aml_declined as terminal — subsequent payments from this agent return AML_DECLINED. See AML Screening.

Merchant events

Type	Fired when
`merchant.kyb.approved`	KYB verification passed; the merchant can receive mainnet settlements
`merchant.kyb.rejected`	KYB verification failed
`merchant.settlement.completed`	A settlement to this merchant completed (merchant-scoped view of `settlement.completed`)

merchant.kyb.approved

{
  "event_id": "evt_0d1c2b3a4f5e",
  "type": "merchant.kyb.approved",
  "created_at": "2026-08-20T09:03:44Z",
  "data": {
    "merchant_id": "mch_1a2b3c4d",
    "legal_name": "Acme Compute Ltd.",
    "kyb_status": "approved",
    "approved_at": "2026-08-20T09:03:44Z"
  }
}

Verifying signatures

Every delivery includes Sohopay-Signature — a hex-encoded HMAC-SHA256 of ${timestamp}.${raw_body} using your endpoint’s signing secret — and Sohopay-Timestamp, the Unix seconds when it was signed. Verify before parsing: recompute the HMAC over the timestamp and the raw request body (never re-serialized JSON), compare in constant time, and reject deliveries older than 5 minutes to block replays.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyWebhook(rawBody: string, signature: string, timestamp: string, secret: string): boolean {
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!Number.isFinite(age) || age > 300) return false;
  const expected = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(signature, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

import hashlib, hmac, time

def verify_webhook(raw_body: bytes, signature: str, timestamp: str, secret: str) -> bool:
    try:
        if abs(time.time() - float(timestamp)) > 300:
            return False
    except ValueError:
        return False
    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Always compare with timingSafeEqual / hmac.compare_digest. A plain == comparison leaks timing information that lets an attacker forge signatures byte by byte.

Delivery, retries, and deduplication

Respond with any 2xx within 10 seconds to acknowledge a delivery. Anything else — a 4xx, 5xx, or timeout — triggers retries at 5s, 30s, 2m, 10m, 1h, then hourly up to 24 hours, after which the delivery is dropped. Retries and network races mean the same event can arrive more than once, so dedupe by event_id: record each processed ID (a unique-constrained column, or a Redis SETNX with a TTL beyond 24 hours) and acknowledge duplicates with a 200 without reprocessing. Ordering is not guaranteed either — a payment.settled can arrive before its payment.created — so key state transitions on resource status, not event arrival order. Acknowledge fast, process async: verify the signature, persist the event, return 200, then handle it from a queue. Slow handlers cause timeouts, which cause retries, which cause the duplicates you then have to dedupe.

Next steps

Webhooks Guide

Error Reference

The error codes behind payment.failed events.

Overview

Endpoints

Event envelope

Event types by resource

Payment events

Settlement events

Agent events

Merchant events

Verifying signatures

Delivery, retries, and deduplication

Next steps

Webhooks Guide

Error Reference

​Event envelope

​Event types by resource

​Payment events

​Settlement events

​Agent events

​Merchant events

​Verifying signatures

​Delivery, retries, and deduplication

​Next steps

Webhooks Guide

Error Reference

Event envelope

Event types by resource

Payment events

Settlement events

Agent events

Merchant events

Verifying signatures

Delivery, retries, and deduplication

Next steps