Webhook problems

Deliveries that fail, arrive twice, or fail signature verification.

Signature

Signature verification fails

This is almost always the raw-body problem.

Careful. Verify against the raw request body. If your framework parses JSON and you re-serialise it to check the signature, key order and whitespace change and every signature fails. Capture the raw bytes before parsing.

See the worked Express example in Node.js examples, including constant-time comparison.

Delivery

Deliveries are not arriving

  1. Check your endpoint is publicly reachableIt must be reachable from the internet over HTTPS, not only from your network.
  2. Confirm it responds 2xx quicklyAcknowledge first, process afterwards. Slow handlers get retried.
  3. Check for a 3xx redirectDeliveries are not followed through redirects — register the final URL.
  4. Look at your own logsA 500 in your handler looks like a failed delivery from our side.
Duplicates

The same event arrives twice

That is expected. Retries mean at-least-once delivery, not exactly-once.

Expected result

Store X-SIMCOAI-Delivery-ID and ignore any id you have already processed. A handler that is not idempotent will eventually double-process an event.

Ordering

Events arrive out of order

Do not assume ordering. Use the event payload and timestamps to reconcile state rather than relying on arrival sequence.