Guide: Provider Verification Matrix
Overview
Syllecta treats provider verification as a contract, not a marketing label. A provider is only listed as production-supported when the inbound signature rules, replay guard, dedupe id, and failure behavior are explicit and tested.
Current Status
| Provider | Status | Raw body verification | Constant-time compare | Timestamp guard | Dedupe id |
|---|---|---|---|---|---|
| Stripe | Supported | Yes | Yes | Yes, 5 minutes by default | event.id |
| Shopify | Supported | Yes | Yes | No provider timestamp; dedupe protects repeated deliveries | X-Shopify-Webhook-Id, fallback payload id |
| GitHub | Supported | Yes | Yes | No provider timestamp; delivery id dedupe protects repeats | X-GitHub-Delivery, fallback payload id |
| Generic HMAC | Supported | Yes | Yes | Yes, 5 minutes by default | payload id or eventId |
| PayPal | Controlled rollout | Yes, current tenant verifier requires PayPal transmission headers and max-age | Yes for the current verifier | Yes, 5 minutes by default | payload id |
| Braintree | Reserved / not production-enabled | Not enabled yet | Not enabled yet | Not enabled yet | Not enabled yet |
Required Headers
| Provider | Required headers | Missing or malformed signature |
|---|---|---|
| Stripe | Stripe-Signature: t=...,v1=... | 400 invalid signature |
| Shopify | X-Shopify-Hmac-Sha256; recommended X-Shopify-Topic, X-Shopify-Webhook-Id | 400 invalid signature |
| GitHub | X-Hub-Signature-256: sha256=...; recommended X-GitHub-Event, X-GitHub-Delivery | 400 invalid signature |
| Generic HMAC | X-Syllecta-Signature: t=...,v1=... | 400 invalid signature |
| PayPal | PayPal-Transmission-Id, PayPal-Transmission-Time, PayPal-Transmission-Sig, PayPal-Auth-Algo, PayPal-Cert-Url | 400 invalid signature |
| Braintree | bt_signature, bt_payload expected by the future official Braintree parser | 400 invalid signature until enabled |
PayPal and Braintree
PayPal and Braintree are intentionally documented separately. PayPal sends transmission headers and is verified through a PayPal webhook-id strategy. Braintree uses bt_signature and bt_payload parsing through the Braintree gateway contract. The Braintree route is reserved so tenants cannot accidentally rely on PayPal-style verification for Braintree traffic.
Before live PayPal/Braintree traffic is accepted for a tenant, the provider-specific verifier must be enabled and tested against that tenant's real provider configuration.
Test Coverage
The Cloud API has table-driven coverage for:
- valid signatures for supported providers;
- modified body after signature generation;
- stale timestamps where the provider contract includes a timestamp;
- replayed event ids through dedupe behavior;
- wrong tenant/provider secret;
- malformed or missing signature headers.