Translation API · Concept
Webhook Verification
Verify Stepes HMAC signatures, reject stale requests, and process lifecycle events idempotently.
Stepes sends signed JSON webhook requests for quote, project, and delivery lifecycle changes. Delivery is at least once, so verify and deduplicate every request.
Required Headers
Content-Type: application/json
User-Agent: Stepes-Webhooks/2.0
Stepes-Webhook-Id: evt_...
Stepes-Webhook-Delivery-Id: whd_...
Stepes-Webhook-Timestamp: 1786219300
Stepes-Webhook-Signature: v1=<64 lowercase hexadecimal characters>Signature Input
<Stepes-Webhook-Timestamp>.<raw_request_body>Compute an HMAC-SHA-256 hexadecimal digest with the endpoint secret. Compare v1=<digest> to each comma-separated signature using a constant-time function. Multiple signatures may be present during secret rotation.
Processing Sequence
1. Read the unmodified raw body. 2. Require all signature headers. 3. Reject a timestamp outside your accepted tolerance; five minutes is recommended. 4. Compute and compare the signature in constant time. 5. Deduplicate by Stepes-Webhook-Id or body id. 6. Durably enqueue/record the event. 7. Return a 2xx response quickly. 8. Process lengthy work asynchronously.
Endpoint and Delivery Safety
Webhook destinations require public HTTPS port 443. Redirects, user-info URLs, localhost, private, link-local, loopback, multicast, reserved, and cloud-metadata destinations are rejected. DNS is revalidated at delivery time.
Failed requests are retried using the documented schedule. A manual retry sends the same persisted event and may duplicate a request that the receiver accepted before its response was lost.