Guide: Webhook Gateway

Overview

Syllecta can act as the first receiver for your providers (Stripe, Shopify, PayPal, Braintree, GitHub). We verify signatures, deduplicate replays, log events, and forward it to your callback URL. This lets you centralize configurations inside Backoffice while the platform handles retries and billing usage.

Flow Summary

1. Receive – Syllecta exposes /v1/webhooks/:provider or /v1/t/:tenantSlug/webhooks/:provider.
2. Verify – provider adapter validates the signature header. Invalid signatures return 400.
3. Deduplicate – events are deduped by tenant + provider + eventId.
4. Log – event metadata is stored for inspection in the dashboard.
5. Forward – Syllecta POSTs the normalized payload to your callback URL.
6. Usage – successful deliveries increment billable usage.

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

Setup

1. Dashboard – under “Webhook settings”, add your signing secret per provider and specify the callback URL.
2. Provider portal – point the provider’s webhook endpoint to https://cloud.syllecta.example/v1/webhooks/<provider> (or slug-specific URL).
3. Testing – use provider CLIs (e.g., stripe listen --forward-to ...) to send sample payloads.

Example Response

POST /v1/webhooks/stripe

200 OK

{
  "ok": true
}

200 OK (duplicate/replay)

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

400 Bad Request (signature failure)

{
  "error": "invalid signature"
}

202 Accepted (queued)

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

Callback Contract

Syllecta forwards a normalized JSON payload containing:

• id (provider event id)
• provider (stripe, generic, shopify, etc.)
• providerRawType (original provider type)
• type (normalized type)
• occurredAt + receivedAt (ISO timestamps)
• payload (provider-specific body)
• headers (original inbound headers)

Requests are sent as JSON with Content-Type: application/json. Respond with any 2xx to stop retries.

References

• Webhook configuration
• Webhooks API
• Examples: Stripe
• Examples: PayPal/Braintree