Getting Started

OverviewQuickstartArchitecture

API Reference

Idempotent RecordsWebhooksContractsAuth / Keys

SDK

InstallUsage

Guides

IdempotencyWebhook GatewayProvider Verification MatrixWebhook ConfigurationData RetentionControlled LaunchSecurity and Data ProtectionSecurity Review PackTraffic ProtectionObservability DashboardChargeback SimulationOnboarding FlowBackoffice Overview

Examples

PaymentsStripePayPal / Braintree StatusGeneric HMACShopifyGitHub

Guide: Webhook Gateway

Overview

Syllecta can act as the first receiver for supported webhook providers. Stripe, Shopify, GitHub, and generic HMAC are production-supported today; PayPal is controlled-rollout; Braintree is reserved until its official parser is enabled. Syllecta verifies signatures, deduplicates replays, logs events, and forwards them to your callback URL.

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://api.syllecta.com/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

json
{
  "ok": true
}

200 OK (duplicate/replay)

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

400 Bad Request (signature failure)

json
{
  "error": "invalid signature"
}

429 Too Many Requests (tenant/provider/IP ingress limit)

json
{
  "error": "rate limited"
}

Valid signed webhooks for suspended tenants return 200 OK, but delivery is paused: Syllecta writes only minimal event evidence, does not forward to the callback URL, and does not store the raw provider payload.

202 Accepted (queued)

json
{
  "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.

Provider-specific signature details are tracked in the Provider verification matrix.

Data Handling

Syllecta is designed around operational metadata first: provider, event id, delivery status, timing, retry state, and failure context. Payload content is used for debug and replay workflows and should be treated as sensitive operational data.

Dashboard event detail uses redacted payload views for routine triage. Tenant payload policy can store metadata only, a redacted payload copy, or raw payloads for a short replay/debug window.

Do not send card data, passwords, access tokens, session cookies, long-lived secrets, or unnecessary personal data in webhook payloads unless the workflow explicitly requires it.

References