Setup in 60 seconds
1
Stand up an endpoint
Any HTTPS URL that responds 2xx within 30 seconds. Keep it cheap;
do the heavy work asynchronously after acknowledging.
2
Subscribe
Create the endpoint via API or dashboard. The response includes a
signing_secret — store it; it’s shown only once.3
Verify and act
On every delivery, recompute the HMAC and compare it constant-time. Reject
requests with a stale timestamp (we recommend a 5-minute window).
Event topics
A complete reference with payload schemas is on the
API reference.
Delivery shape
Verifying the signature
The signature is a hex-encoded HMAC-SHA256 of the raw body (do not parse and re-stringify) using yoursigning_secret. The header is
t=<unix>,v1=<hex>; future signature versions will append additional
algorithms (e.g. v2=).
Retry behavior
If your endpoint doesn’t respond2xx within 30 seconds, we retry with
exponential backoff: 30 s, 2 m, 10 m, 1 h, 6 h. After 5 failed attempts the
delivery is marked failed and visible in the dashboard.
You can manually replay any past delivery from the dashboard or via the API:
data payload is always the resource as it stood at delivery time
(not the resource as it stands now). A redeliver replays the original payload.
Best practices
Acknowledge fast, work async
Acknowledge fast, work async
Return
2xx as soon as you’ve persisted the raw payload (or queued a job).
Don’t run business logic in the request handler — anything over a few
seconds risks a retry that double-processes.Idempotent processing
Idempotent processing
Treat
X-Neural-Draft-Delivery as the dedupe key. Index it; reject (and
2xx) duplicates. Retries happen — they’re a feature, not a bug.Replay protection
Replay protection
Reject deliveries with timestamps more than 5 minutes off. The verifier
helpers above do this for you.
Rotate secrets
Rotate secrets
Rotate the signing secret quarterly, or instantly if you suspect a leak.
The dashboard supports a transition window — both old and new secrets
accepted for up to 24 hours.
Monitor failures
Monitor failures
Watch the
last_delivery_status field on the endpoint resource (also
visible in the dashboard’s delivery log). A failed state for more than
an hour is your cue to investigate.Use one endpoint per concern
Use one endpoint per concern
A single endpoint subscribed to many topics is fine; the
X-Neural-Draft-Event
header tells you which one. But splitting concerns by URL (orders, content,
bookings) makes failure isolation cleaner.