تخطَّ إلى المحتوى

Connect via Custom Webhook

هذا المحتوى غير متوفر بلغتك بعد.

If your platform already fires outbound webhooks when an order is placed, point one at SamVertex. The body is the same order JSON as the REST API; the difference is that each request is signed, so we can trust it came from you.

Endpoint, key, and signature

Section titled “Endpoint, key, and signature”
POST https://api.samvertex.com/ingest/webhook
Authorization: Bearer <your api key>
x-svx-signature: sha256=<hex HMAC-SHA256 of the raw body>
Content-Type: application/json

Two checks run on every request:

  • The Bearer key identifies your account, exactly as on the REST API.
  • The x-svx-signature header proves the body was not altered. It is the HMAC-SHA256 of the exact raw request body, in lowercase hex. A sha256= prefix is accepted and recommended.

Sign the bytes you actually send, before any reformatting. If you pretty-print or re-serialise the JSON after signing, the signature will not match.

Your signing secret

Section titled “Your signing secret”

Your signing secret is shown in the portal Integrations card under the webhook details. It is unique to your account. Keep it server-side; never put it in a browser or a public repository. If the webhook details show that signing is not yet available for your account, contact us to switch it on.

The order body

Section titled “The order body”

The body is the canonical order object documented on the REST API page: source_order_id is required, the rest is best effort.

Re-delivery and duplicates

Section titled “Re-delivery and duplicates”

Webhooks retry. That is safe here. We deduplicate on your source_order_id, so a redelivered order does not create a second SamVertex order. If your platform sets a stable id per delivery, you can also send it as an Idempotency-Key header and we will return the original receipt for a repeat.

Example signature

Section titled “Example signature”

  1. Take the raw body you are about to send, as bytes.

  2. Compute the HMAC with your secret. In Node:

    import crypto from 'node:crypto';
    const sig = crypto.createHmac('sha256', SVX_WEBHOOK_SECRET)
      .update(rawBody)        // the exact bytes you POST
      .digest('hex');
    // send header:  x-svx-signature: sha256=<sig>

  3. POST the body to /ingest/webhook with the Authorization and x-svx-signature headers. A correct request returns 202 { receipt_id }, the same receipt as the REST API.

Orders sent by webhook land in Needs review and do not dispatch until confirmed. Track results on the receipts, status, and errors page.