Webhooks

Inbound endpoint (v1)

Primary URL

POST https://raffssync.io/webhooks/v1/{provider}

{provider} is a short provider code such as takeapp, iseller, accurate. This keeps setup human-readable and routing unambiguous.

Optional topic tail

POST https://raffssync.io/webhooks/v1/{provider}/{topic}

The {topic} segment is optional. RaffsSync primarily routes by signed identity + event type in headers/body, and uses the topic tail as a compatibility hint when a provider’s webhook settings are limited.

---

Health check (GET)

GET https://raffssync.io/webhooks/v1/{provider}

Returns a minimal JSON “alive” response for setup/testing. No secrets, no environment leakage.

Routing examples

Use the provider code as the routing key.

POST /webhooks/v1/takeapp
POST /webhooks/v1/iseller
POST /webhooks/v1/accurate

When a provider forces “topic style” endpoints, you can append a tail:

POST /webhooks/v1/takeapp/orders
POST /webhooks/v1/iseller/inventory
POST /webhooks/v1/accurate/journal

Response codes

• 200 — accepted (processed or queued safely)
• 202 — accepted for async processing
• 400 — invalid payload (don’t retry until fixed)
• 401/403 — signature/auth failed
• 409 — duplicate (idempotency hit; safe to stop retries)
• 429 — rate limited (retry with backoff)
• 500 — transient server error (retry with backoff)

Providers should retry on 429 or 5xx with exponential backoff.

Retries & idempotency

RaffsSync is designed to be retry-safe. Providers must send a stable event ID if available.

Recommended

• Send an event ID header (or include an ID field in payload)
• Retry only on 429 / 5xx
• Use exponential backoff + jitter

If the same event is delivered twice, RaffsSync should treat it as a duplicate rather than a second “real” action.

Signature verification

Signature model varies by provider (OAuth, HMAC, bearer, etc.). Provider guides document their expected verification method.

Tip

If you’re unsure which signature model applies, open the provider guide and check the “Verification” card.

Operational notes

- Always respond quickly (queue processing if needed).
- Never expose secrets in responses.
- Keep payload logging minimal and redact sensitive fields.
- Prefer idempotent processing per event ID.