Delivery, retries & onboarding

Acknowledging a delivery

Respond with any 2xx status to acknowledge a delivery. Anything else — a non-2xx status, a connection error, or a response taking longer than 10 seconds — counts as a failed attempt.

Acknowledge first, process later. Verify the signature, persist the event, return 2xx immediately, and do the heavy processing asynchronously. Slow synchronous processing risks hitting the 10-second timeout and causing unnecessary redeliveries.

Retries

Failed deliveries are retried with exponential backoff — delays of roughly 1, 2, 4 and 8 minutes between successive attempts, for 5 attempts in total. After the last failed attempt the delivery is parked on our side and our team is alerted; once you have fixed the issue on your end, contact us and we redeliver the parked events.

At-least-once delivery and deduplication

The same event can reach you more than once — retries after a timeout you actually processed, or redelivery after an outage. Deduplicate on eventId: it is stable for the lifetime of the event, across every delivery attempt. The X-Callplus-Event-Id header carries the same value, so you can dedup before parsing the body.

Ordering

Delivery order is not guaranteed — two events may arrive in any order, especially around retries. Treat each event independently; use occurredAt if you need a business timeline.

Endpoint requirements

• A publicly reachable HTTPS endpoint (https:// is required; plain HTTP is not accepted).
• Responds 2xx within 10 seconds.
• Verifies the X-Callplus-Signature header on every request — see Verifying webhook signatures.
• You can register separate endpoints for the pilot phase and production.

The shared secret

• We generate the secret at onboarding: 64 hexadecimal characters (32 bytes of entropy), exchanged with you through a secure out-of-band channel — never over email in clear text, and never via the webhook itself.
• Store it in a secrets manager; never commit it to version control or write it to logs.
• To rotate a secret (periodically or after a suspected compromise), contact us — rotation is coordinated so the switch happens at an agreed moment.

Per-firm consent and activation

Events that carry an accounting firm's data are only delivered under that firm's explicit consent:

• Each firm is activated individually, with an agreed activation date.
• You only receive plan.launched events for plans whose entry date is on or after that firm's activation date. An activation date in the past is a deliberate, agreed backfill.
• A plan whose entry date is missing or invalid on our side is withheld (fail-closed): it is never delivered while the activation-date check cannot be performed, and is released once the date is corrected. Delivered events therefore always carry a valid entryDate.
• Consent is checked at delivery time — if a firm's consent is withdrawn, deliveries for that firm stop immediately, including retries of already-queued events.
• Events for firms without consent are simply never delivered to you; there is no notification of skipped events.

Security and data protection

Webhook payloads contain personal data (national register numbers, names, email addresses) and remuneration data. Before going live:

• A data processing agreement (DPA) between your organization and Call+ must be in place.
• Restrict access to the data on your side to what your use case needs, and apply your retention and erasure obligations to stored payloads.
• Report any suspected leak of the payload data or of the signing secret to us immediately.

Onboarding checklist

1. Contact us at [email protected] to start the onboarding.
2. Exchange endpoint URLs (pilot + production) and receive the signing secret.
3. Sign the data processing agreement.
4. Agree the subscription list (event types) for your integration.
5. Confirm the field list of the plan.launched event covers your use case.
6. Pilot: we deliver test events to your pilot endpoint; you confirm signature verification and deduplication work — Building a webhook receiver has a runnable starting point and the test checklist.
7. Go live per firm: each accounting firm is activated individually, with an agreed activation date.