Best practices

Always verify signatures

Without verification, anyone who discovers your endpoint URL could send fake events to trigger real actions in your system. Never process a payload before confirming its Synup-Signature header.

Handle duplicate deliveries

Retries and replays mean your endpoint may receive the same event more than once. Store the envelope's id and skip any event you've already processed, rather than assuming each delivery is unique.

Respond quickly, process asynchronously

Return a 2xx status as soon as you've confirmed the signature and queued the event — before running slow logic like sending emails or calling other APIs. A slow response counts as a failed delivery and triggers a retry, which can leave you processing the same event twice.

Only subscribe to what you use

Narrow your endpoint's events down to what your integration actually handles from the Events tab. Fewer events means fewer deliveries to secure, log, and reason about.

Rotate your signing secret periodically

Treat your webhook secret like any other credential. Rotate it periodically, or immediately if you suspect it's been exposed — the 7-day overlap window means you can deploy the new secret without dropping any deliveries.

HTTPS is required, and your certificate must be valid

Deliveries to a URL with an invalid, expired, or self-signed certificate fail before your endpoint code ever runs. Use a certificate from a trusted authority — most hosting platforms provision one automatically.