Best practices
Verify every signature
Never act on a webhook you have not verified. Reject requests whose signature does not match or whose timestamp is more than 5 minutes old.
Answer fast, work later
Return 2xx as soon as the signature is verified and the event is stored, then process it in a
background job. Your handler must answer within 10 seconds; slow work in the request path turns
into timeouts, then into retries, then into duplicates.
Deduplicate on the event ID
The same event can be delivered more than once (retries, manual resends). Store the IDs of the
events you processed (X-Skoup-Event-Id or the body’s id) and skip the ones you already know.
Do not rely on order
Deliveries are not guaranteed to arrive in the order events happened. When order matters, compare
the created timestamps, or fetch the object’s current state from the API.
Subscribe only to what you use
Pick the event types your integration handles instead of *. You receive less traffic, and new
event types added to Skoup will not surprise your handler.
Handle unknown fields
Payloads grow over time — new fields are added within v1. Ignore the fields you do not know instead of failing on them.
Testing locally
Skoup only delivers to public HTTPS URLs. To receive events on your machine, open a tunnel to your local server and register the tunnel URL as a test endpoint:
ngrok http 3000
# Forwarding https://4f2a-81-23-45-67.ngrok-free.app -> http://localhost:3000Then use Send test event on the endpoint, or create a task with a test key — the matching
task.created event reaches your machine in seconds.