Sinbad Partner API

Before you receive events

Register an endpoint, store its signing secret, and verify the receiver.
Subscribe the endpoint to this event type.
Verify the timestamp and signature against the raw request body before you parse or acknowledge it. See Webhooks.

POST <your receiver URL>
Content-Type: application/json
Sinbad-Webhook-Id: evt_demo
Sinbad-Webhook-Timestamp: <Unix seconds>
Sinbad-Webhook-Signature: v1=<keyId>:<HMAC-SHA256 hex>

Payload examples

Customer text

{
  "id": "evt_demo",
  "type": "trade.message.created",
  "apiVersion": "2026-10-22",
  "environment": "sinbad-staging-env",
  "partnerId": "partner_demo",
  "integrationId": "integration_demo",
  "partnerUserId": "customer_demo",
  "tradeId": "trade_demo",
  "sequence": 3,
  "occurredAt": "2026-10-23T10:00:00.000Z",
  "sourceCommittedAt": "2026-10-23T10:00:00.000Z",
  "recordedAt": "2026-10-23T10:00:00.000Z",
  "data": {
    "message": {
      "messageId": "message_demo",
      "authorRole": "customer",
      "type": "text",
      "text": "Payment sent.",
      "createdAt": "2026-10-23T10:00:00.000Z",
      "proofId": null,
      "attachment": null
    }
  }
}

Customer image

{
  "id": "evt_demo",
  "type": "trade.message.created",
  "apiVersion": "2026-10-22",
  "environment": "sinbad-staging-env",
  "partnerId": "partner_demo",
  "integrationId": "integration_demo",
  "partnerUserId": "customer_demo",
  "tradeId": "trade_demo",
  "sequence": 3,
  "occurredAt": "2026-10-23T10:00:00.000Z",
  "sourceCommittedAt": "2026-10-23T10:00:00.000Z",
  "recordedAt": "2026-10-23T10:00:00.000Z",
  "data": {
    "message": {
      "messageId": "message_demo",
      "authorRole": "customer",
      "type": "image",
      "text": "Receipt",
      "createdAt": "2026-10-23T10:00:00.000Z",
      "proofId": null,
      "attachment": {
        "kind": "image",
        "contentType": "image/png",
        "size": 68,
        "metadataStatus": "available"
      }
    }
  }
}

Customer file

{
  "id": "evt_demo",
  "type": "trade.message.created",
  "apiVersion": "2026-10-22",
  "environment": "sinbad-staging-env",
  "partnerId": "partner_demo",
  "integrationId": "integration_demo",
  "partnerUserId": "customer_demo",
  "tradeId": "trade_demo",
  "sequence": 3,
  "occurredAt": "2026-10-23T10:00:00.000Z",
  "sourceCommittedAt": "2026-10-23T10:00:00.000Z",
  "recordedAt": "2026-10-23T10:00:00.000Z",
  "data": {
    "message": {
      "messageId": "message_demo",
      "authorRole": "customer",
      "type": "file",
      "text": "Receipt",
      "createdAt": "2026-10-23T10:00:00.000Z",
      "proofId": null,
      "attachment": {
        "kind": "file",
        "contentType": "application/pdf",
        "size": 68,
        "metadataStatus": "available"
      }
    }
  }
}

Merchant text

{
  "id": "evt_demo",
  "type": "trade.message.created",
  "apiVersion": "2026-10-22",
  "environment": "sinbad-staging-env",
  "partnerId": "partner_demo",
  "integrationId": "integration_demo",
  "partnerUserId": "customer_demo",
  "tradeId": "trade_demo",
  "sequence": 3,
  "occurredAt": "2026-10-23T10:00:00.000Z",
  "sourceCommittedAt": "2026-10-23T10:00:00.000Z",
  "recordedAt": "2026-10-23T10:00:00.000Z",
  "data": {
    "message": {
      "messageId": "message_demo",
      "authorRole": "merchant",
      "type": "text",
      "text": "Payment sent.",
      "createdAt": "2026-10-23T10:00:00.000Z",
      "proofId": null,
      "attachment": null
    }
  }
}

Merchant image

{
  "id": "evt_demo",
  "type": "trade.message.created",
  "apiVersion": "2026-10-22",
  "environment": "sinbad-staging-env",
  "partnerId": "partner_demo",
  "integrationId": "integration_demo",
  "partnerUserId": "customer_demo",
  "tradeId": "trade_demo",
  "sequence": 3,
  "occurredAt": "2026-10-23T10:00:00.000Z",
  "sourceCommittedAt": "2026-10-23T10:00:00.000Z",
  "recordedAt": "2026-10-23T10:00:00.000Z",
  "data": {
    "message": {
      "messageId": "message_demo",
      "authorRole": "merchant",
      "type": "image",
      "text": "Receipt",
      "createdAt": "2026-10-23T10:00:00.000Z",
      "proofId": null,
      "attachment": {
        "kind": "image",
        "contentType": null,
        "size": null,
        "metadataStatus": "unavailable"
      }
    }
  }
}

Merchant file

{
  "id": "evt_demo",
  "type": "trade.message.created",
  "apiVersion": "2026-10-22",
  "environment": "sinbad-staging-env",
  "partnerId": "partner_demo",
  "integrationId": "integration_demo",
  "partnerUserId": "customer_demo",
  "tradeId": "trade_demo",
  "sequence": 3,
  "occurredAt": "2026-10-23T10:00:00.000Z",
  "sourceCommittedAt": "2026-10-23T10:00:00.000Z",
  "recordedAt": "2026-10-23T10:00:00.000Z",
  "data": {
    "message": {
      "messageId": "message_demo",
      "authorRole": "merchant",
      "type": "file",
      "text": "Receipt",
      "createdAt": "2026-10-23T10:00:00.000Z",
      "proofId": null,
      "attachment": {
        "kind": "file",
        "contentType": null,
        "size": null,
        "metadataStatus": "unavailable"
      }
    }
  }
}

Your response

Return a 2xx response once you have durably stored the event. Deduplicate on the signed event ID: retries and manual replays keep the same ID.

Trade and message events share one sequence counter, so gaps are normal if you subscribe to only some event types. A message can arrive after a newer trade update, so do not treat arrival order as the complete history of a trade. List the trades to reconcile.

If an attachment is unavailable, the payload says so explicitly. Read the original attachment through the authenticated API.

These payloads are synthetic examples.