On this page
Make streaming webhooks safe to retry
Treat a webhook as a message that may arrive again. Verify its signature over the raw body, save the accepted event durably, deduplicate it and process it separately. A signed request proves authenticity; it does not make your database update happen exactly once.
- EventIdentify the same delivery
- ReceiverStore its identity
- ActionApply the change once
The failure that creates duplicate work
Your system receives video.ready, creates a publishing job and sends a
response. The connection breaks before creekX sees that response. From your database’s
point of view the work happened. From the sender’s point of view delivery failed. A retry
can create a second publishing job unless the receiver remembers the first.
This is an ordinary distributed-system problem, not proof the sender made two events. Design for it before attaching payments, emails or publishing actions. The HTTP semantics standard explains idempotency and retry considerations. An HTTP POST is not automatically safe to repeat because its payload is identical.
Know what creekX sends
In Settings → Webhooks, add an HTTPS receiver, choose events and save the
signing secret securely when it is shown. The
automation guide describes the controls. Events include
stream.live, stream.ended, recording.saved and
video.ready; choose the one matching your task.
The request includes CreekX-Delivery, CreekX-Event and
CreekX-Signature. Its JSON envelope includes an event id, type,
time, sequence and data. A recording being saved and a library video being ready are
different stages. Do not start a task requiring a playable video merely because its
recording entered the library.
Verify bytes before trusting fields
The signature header has the shape t=…,v1=…. creekX signs the timestamp, a
dot and the exact body with HMAC-SHA256. Capture the body before a JSON parser changes
spacing or encoding. Parse the signature strictly, compute the expected value and compare
using your platform’s constant-time comparison.
Apply a deliberate timestamp policy too. For example, a five-minute tolerance can be a receiver policy when its clock is kept in sync; it is not a universal requirement. The current sender signs each attempt with its sending time. A valid signature alone does not prevent replay inside your allowed window.
Split receiving from doing
receive raw bytes
verify signature and timestamp
validate the event shape
begin transaction
insert inbox row with a unique source + event/action key
if the row already exists: do not repeat the side effect
commit the durable inbox row
return a successful HTTP response
process pending rows in a separate worker
This is a design outline, not a complete receiver. Enforce body-size limits, authentication expectations and database constraints. If saving the inbox fails, do not answer as if the event was safely accepted. Once it is durable, a slow downstream API should not hold the sender’s connection open while your job runs.
Choose the deduplication boundary
Use CreekX-Delivery to recognise attempts for a particular delivery. For a
task that must run once for an event, a durable key based on the payload event ID and your
action is often a better boundary. Include the trusted source or installation in the key.
Do not accept an unauthenticated field as proof of customer ownership.
Make the side effect idempotent where possible. A unique job row helps, but a worker can crash after calling an external service and before recording success. Use that service’s supported idempotency mechanism, or keep a reconciliation process. A memory-only set disappears on restart and is not durable deduplication.
Test the receiver’s bad day
- Send the configured test event and check the delivery result.
- In a private test environment, return a failure and observe a later attempt.
- Accept the same validated event twice; verify only one task is created.
- Delay the receiver beyond the sender’s timeout and check duplicate handling.
- Restart the worker after intake; confirm pending jobs remain.
- Reject a changed body and stale signature without executing the action.
creekX’s current default sender timeout is ten seconds. It records attempts and retries failures on a widening schedule. Inspect recent deliveries rather than assuming a retry arrived. Pair this with the API quick start, a recovery drill and the streaming server guide. Keep secrets and full private request bodies out of logs and screenshots.
Implementation check
Reproduce the lost-acknowledgement case
You need: A private HTTPS receiver, a test webhook secret and a durable event store.
- Verify the raw bytes and signature before parsing JSON or creating work.
- Commit the accepted event and deduplication key, then simulate the response being lost.
- Deliver the same event again and verify only one downstream job is created. Reconcile missed state using the API as well.
Pass when: A retry can be acknowledged safely after a durable write; duplicate delivery does not duplicate the side effect.
If it fails: An in-memory Set loses deduplication on restart. A delivery ID and a business-event ID answer different deduplication questions.
Frequently asked questions
Does a successful webhook guarantee my job finished?
No. A 2xx response confirms the receiver accepted the request according to its own contract. If it queues work, monitor that work separately.
Should I deduplicate by delivery ID or event ID?
Use the identifier matching your side effect. The delivery ID identifies delivery to an endpoint; the payload event ID identifies the event. Scope stored keys to the source and action.