Webhooks

Webhook configuration isn't self-service yet. Contact your Intasef account contact to register your webhook URL and receive your signing secret. The Partner Portal Webhooks page shows delivery history once your webhook is configured, but it doesn't let you register or rotate a webhook yourself — and the API Keys page holds a different kind of secret (your HMAC signing keys, not your webhook secret).

Event types

  • trade.{status} — fires on every trade status change (e.g. trade.funded, trade.released)
  • seller.{status} — seller onboarding status changes
  • buyer.{status} — buyer onboarding status changes (Marketplace partners with KYC-gated buyers only)

Payload shape

{
  "trade_id": "...",
  "reference": "...",
  "status": "funded",
  "external_reference": "your-own-order-id-123"
}

Verifying a delivery

Every delivery includes:

  • X-Intasef-Signature — sha256=<hex digest>, an HMAC-SHA256 of the raw request body using your webhook secret
  • X-Intasef-Delivery-Id — a unique ID per delivery attempt, for deduplication on your end

Recompute the HMAC over the exact raw bytes you received and compare it against the signature header before trusting the payload.

Retries and fallback

Failed deliveries retry with exponential backoff, up to 6 attempts total (the initial delivery plus 5 retries). If a delivery is ever missed entirely, GET /api/partner/v1/trades/{id}/ is always available as a fallback — webhooks are the primary channel, polling is the safety net.