API: Webhooks

Overview

Endpoints:

• POST /v1/webhooks/:provider
• POST /v1/t/:tenantSlug/webhooks/:provider

They normalize provider payloads, validate signatures, dedupe events, and forward to your callback URL with automatic retries.

Request path

• :provider — stripe, generic, shopify, github; paypal is controlled-rollout; braintree is reserved until its official verifier is enabled.
• Optional :tenantSlug for slug-based delivery (no API key required). Slug is resolved via your tenant configuration.

Headers vary per provider.

Sample: Stripe

POST /v1/webhooks/stripe
Stripe-Signature: t=...,v1=hex
Content-Type: application/json

Sample: Generic HMAC

POST /v1/t/acme-payments/webhooks/generic
X-Syllecta-Signature: t=1692059,v1=cafebabe123...
Content-Type: application/json

Signature computed as HMAC_SHA256(secret, "${timestamp}.${rawBody}").

Flow

1. Authenticate – via API key (Authorization: Bearer ck_...) or tenant slug route.
2. Validate – provider adapter verifies the signature header using the secret configured in your dashboard. Invalid signatures return 400.
3. Deduplicate – events are deduped by tenant + provider + eventId. Duplicates return 200 with cached: true.
4. Log – event metadata is stored so you can inspect each event in the dashboard.
5. Forward – Syllecta POSTs the normalized payload to your callback URL. Final status (processed/delivery_failed) is shown in the dashboard.

In rare cases the API may respond with 202 and queued: true when processing is delayed.

Data handling

Syllecta stores operational metadata for observability and may store raw payload/debug data within the configured retention window for replay and troubleshooting. Routine dashboard views use redacted payloads.

Avoid sending card data, passwords, access tokens, session cookies, long-lived secrets, or unnecessary personal data in webhook payloads. See Security and data protection before connecting real customer traffic.

Forwarded payload

Syllecta forwards a normalized JSON payload to your callback URL:

{
  "id": "evt_...",
  "provider": "stripe",
  "providerRawType": "charge.dispute.updated",
  "type": "chargeback.under_review",
  "tenantId": "...",
  "occurredAt": "2026-02-23T02:59:56.000Z",
  "receivedAt": "2026-02-23T02:59:56.000Z",
  "payload": { ... },
  "headers": { ... }
}

Forwarded requests are sent as JSON with Content-Type: application/json.

Response structure

200 OK

{
  "ok": true
}

200 OK (dedup hit)

{
  "ok": true,
  "cached": true
}

202 Accepted (queued)

{
  "ok": true,
  "queued": true
}

400 Bad Request (invalid signature)

{
  "error": "invalid signature"
}

400 Bad Request (missing event id)

{
  "error": "missing event id"
}

403 Forbidden

{
  "message": "tenant not allowed"
}

Providers

Related guides

• Webhook configuration
• Webhook gateway
• Provider verification matrix
• Security and data protection
• Examples: Stripe
• Examples: PayPal/Braintree status