Webhook FAQ
Quick answers to the questions merchants ask most often.
Can I have multiple endpoints?
Yes. You can register up to 50 active endpoints per environment per organization. Each endpoint has its own URL, event subscription list, signing secret, and state. Use multiple endpoints when:
- You want separate receivers for different event categories (e.g., one for payments, one for settlements).
- You're migrating between systems — run both in parallel until the new one is ready.
- You operate multiple acceptors and want to route their events to different teams.
What's the difference between static and per-payment webhooks?
| Static endpoint | Per-payment webhook_url | |
|---|---|---|
| Scope | Whole organization (optionally one acceptor) | One specific payment |
| Configured | Once, in the Dashboard | Per payment, in create_payment |
| Receives | All matching events for the org | Events for that one payment + its refunds + chargebacks |
| Signing | Per-endpoint secret, rotatable | Per-acceptor secret |
| Lifecycle events (settlements, org changes) | Yes | No |
Both fire in parallel today. We recommend adopting static endpoints for new integrations.
Do static and per-payment webhooks fire together?
Yes — for now. If you've configured a per-payment webhook_url AND a matching static endpoint, we deliver to both. This makes the migration safe: stand up the static endpoint, verify it receives everything you need, then drop the per-payment webhook_url from your create_payment calls.
Future releases may collapse the two paths once enough merchants have migrated. We will announce any change at least 90 days in advance.
What happens during rotation?
We generate a new signing secret, mark it active, and set the old one to expire in 24 hours. During that 24-hour grace period both secrets are valid. Each delivered event carries a signature-secret-id header indicating which secret signed it; your receiver looks up the secret by that id and verifies.
After 24 hours the old secret expires. Subsequent events carry only the new id. Remove the old secret from your store.
See Webhook Signing Secrets for the full flow.
How long do you retry failed deliveries?
We retry with exponential backoff for up to 46 hours, after which the delivery is marked as failed. Test and live endpoints use the same retry schedule.
After too many consecutive failures the endpoint transitions to auto_disabled and we stop attempting delivery until you re-enable it from the Dashboard. This protects your dashboard view of healthy endpoints from being drowned out by a misconfigured one.
What's the request timeout?
We give your receiver 30 seconds to respond with 2xx. 5xx responses, timeouts and connection errors are retried per the schedule above. Permanent 4xx responses (400, 401, 403, 404 etc.) are treated as handler bugs and not retried; 408 (request timeout), 425 (too early), and 429 (rate limited) ARE retried.
If your processing is heavy, return 2xx quickly and process asynchronously on your side.
Can I subscribe to a single event type?
Yes. When creating the endpoint, instead of selecting *, choose specific event types like transactions.payment.paid or wildcards like transactions.payment.*. We only deliver matching events to that endpoint.
The Dashboard's autocomplete is fed by the live event catalog, so available subscriptions stay in sync with what we emit.
Are events ordered?
No. Plan for out-of-order arrival. Use the triggered_at field on each event to reconstruct timelines on your side. Two events for the same payment can arrive in any order, especially during retries.
If you need strict ordering for a state machine, gate state transitions on triggered_at >= last_processed_at for that payment.
How do I know if my endpoint is healthy?
The Dashboard shows the endpoint state, the number of consecutive failures, and the timestamp of the last successful delivery. The audit log records every state change. The Dashboard surfaces delivery latency and success rate per endpoint. Account-level webhook-health alerting is on the roadmap.
What if my secret leaks?
Rotate immediately:
- Open the endpoint in the Dashboard.
- Click the row menu and choose Rotate secret.
- Update your receiver with the new secret.
The audit log captures the rotation event (actor, IP, timestamp) — useful evidence for your incident report.
Can I see the plaintext secret again after creating?
Yes — open the endpoint's row menu and choose Secret anzeigen. The plaintext is shown once over your authenticated session and is never persisted. Every reveal is audit-logged with your account, IP and timestamp, and only users with the reveal_secret permission can trigger it.
If you only need a fresh secret for routine rotation, prefer Rotate secret (Secret rotieren in the German dashboard) — it generates a new key, preserves the old one for 24 h, and avoids the audit entry that recovery flows produce.
Is the audit log mine to keep?
The audit log is per-endpoint and visible to your team in the Dashboard for the full lifetime of the endpoint (and after soft-deletion, for retention purposes). We retain audit rows at least one year online and three years total — matching the PCI DSS 10.5.1 requirement. If you need an export for your own retention systems, contact support.
Can I disable an endpoint without losing the configuration?
Yes — set its state to disabled from the Dashboard. We stop attempting delivery, but the endpoint, its event subscriptions and its secret stay in place. Switch back to active and delivery resumes (no events are backfilled while disabled).
What if I have a question that's not here?
Email support, or reach out via the dashboard's chat if you have it enabled. We track common questions and will keep this FAQ updated.