Skip to main content
Xquik signs every X (Twitter) webhook delivery with HMAC-SHA256. It signs a string built from a timestamp, nonce, and the raw body. Verify the signature and reject stale or replayed requests before processing events.

Headers sent with every delivery

Read these headers from each webhook POST before parsing the JSON body. Trust only the signature. Use Content-Type and User-Agent only for handler routing and logs.

Timestamp

X-Xquik-Timestamp is Unix epoch milliseconds. Reject requests outside the 5-minute tolerance window.

Nonce

X-Xquik-Nonce is 16 random bytes in hex. Store recent values for 5 minutes and reject repeats.

Signature

X-Xquik-Signature is sha256=<hex> over <timestamp>.<nonce>.<rawBody> keyed with the endpoint secret.

Raw JSON body

Content-Type is always application/json. Verify the raw body bytes before parsing or re-serializing JSON.

Sender logs

User-Agent is xquik-webhooks/1.0 (+https://xquik.com). Log it for diagnostics. Never trust it instead of the signature.

How it works

  1. Xquik computes the signing string <timestamp>.<nonce>.<rawBody>.
  2. Xquik computes sha256= + HMAC-SHA256(webhook secret, signing string).
  3. Your server recomputes the signature with the same secret over the raw body.
  4. Reject the request if the signature does not match in constant time.
  5. Reject the request if the timestamp is older than 5 minutes (clock-skew tolerant).
  6. Reject the request if the nonce was already seen in the last 5 minutes. This check is replay protection.

Receiver hardening handoff

Use this handoff when you promote a webhook receiver. This handoff covers the step from a signed test request to production monitor events. It keeps signing, replay protection, idempotency, and incident routing visible in one review record.

Raw body first

Keep raw request bytes available until signature verification succeeds. Parse JSON only after the HMAC check passes.

Nonce store

Store each nonce with the webhook ID for 5 minutes. Reject duplicates before queueing or acknowledging the event.

Secret hygiene

Store the webhook secret once. Use it only for HMAC checks. Never write it to logs, queues, traces, or incident rows.

Incident fields

Send status, attempts, lastStatusCode, lastError, createdAt, and deliveredAt from the deliveries API. Send them to your alerting or support queue.

Implementation

The same check is ready in Python webhook verification and Go webhook verification.

Security checklist

Never process webhook payloads without verifying the signature first. An unverified payload could be a spoofed request.
Use timingSafeEqual (Node.js), hmac.compare_digest (Python), or hmac.Equal (Go). String equality (===) is vulnerable to timing attacks.
Compute the HMAC over the raw request body bytes, not a re-serialized JSON object. Re-serialization can alter whitespace or key ordering.
Respond within 10 seconds. Process events asynchronously if your handler is slow.

Idempotency

Xquik retries failed webhook deliveries. Your endpoint may receive the same event more than once. See webhook idempotency for the dedupe patterns.