← BlogOperations8 min read

By creekX product team, Product documentation

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.

Webhook delivery sequence with signature check, durable inbox, duplicate handling and worker
Accept a message durably before doing slow work.
Event: Identify the same delivery; Receiver: Store its identity; Action: Apply the change once
  1. EventIdentify the same delivery
  2. ReceiverStore its identity
  3. ActionApply the change once
A retry is normal; duplicate side effects are avoidable. Concept diagram; not a performance chart.
Developers contains API recipes and API keys; private connection details are hidden
Developers contains API recipes and API keys; private connection details are hidden. Open full screenshot.

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

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.

  1. Verify the raw bytes and signature before parsing JSON or creating work.
  2. Commit the accepted event and deduplication key, then simulate the response being lost.
  3. 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.

Follow the product steps

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.

Follow the build