Troubleshooting & Best Practices

Best practices

Acknowledge fast, process later

DevStride waits at most 10 seconds for an answer, and sends deliveries to one endpoint one at a time, so the time your receiver takes to answer is the speed of its queue. Do the minimum in the request:

1. verify the signature;
2. store the event (a job queue, a database row, a message on SQS, Pub/Sub or Kafka);
3. answer 2xx with an empty body.

Then do the real work (calling other APIs, updating records, posting to chat) in a separate worker. Answering before the event is stored safely risks losing it if your process crashes in between; answering after storing it is the safe order.

Verify before you trust anything

Check X-DevStride-Signature on every request, against the raw body, before you parse it or act on it. Reject failures with 401. A request that fails verification is either not from DevStride or was altered on the way; nothing in it should reach your systems. The Verifying Signatures page has tested code for six languages.

Deduplicate by event id

Delivery is at least once, so the same event can arrive twice. Record every event id you have processed and skip repeats:

CREATE TABLE devstride_webhook_events (
  event_id    uuid        PRIMARY KEY,
  received_at timestamptz NOT NULL DEFAULT now()
);

-- In the same transaction as the work the event causes:
INSERT INTO devstride_webhook_events (event_id) VALUES ($1)
ON CONFLICT (event_id) DO NOTHING;
-- 0 rows inserted: you have already handled this event; skip it.

Keep ids for at least 30 days, the period over which a delivery can be replayed, then delete old rows. The id is the same on every retry and replay, and the same for every endpoint that receives the event.

Answer 2xx to everything you verified

Any status other than 2xx is retried for about a day and, while it is, holds up every newer delivery to that endpoint. So:

• answer 2xx to event types you do not handle, including ping and types added in future;
• answer 2xx to an event your code cannot process (a bug, an unexpected value), store it, and alert yourself, rather than letting it block the queue;
• reserve error statuses for "try again later" situations you expect to clear, such as your database being briefly unavailable.

Be ready for any order

Within one endpoint deliveries arrive in the order DevStride queued them, but across endpoints there is no order at all, and two changes made almost at once can be queued the other way round. When order matters:

• compare occurredAt and ignore an event older than the state you already hold;
• for status changes, check that previousStatusId matches the status you have on record;
• when in doubt, treat the event as a signal and read the current state from the API by the ids it carries.

Ignore what you do not recognize

New fields and event types are added without notice. Read the fields you need, ignore unknown keys, and never fail on an unknown type. See Compatibility.

Filter internal notes and drop your own echoes

comment.created includes internal notes: check visibility is public before showing a comment to anyone outside your team. If your integration also writes to DevStride (for example syncing comments back), run it as a dedicated member and skip events whose origin.actorId is that member's username, so you do not process your own writes as new ones.

Protect the secret

Keep each endpoint's secret in a secret manager or environment variable, never in source code or logs. Use a different endpoint, and so a different secret, for each system and environment (production and staging should never share one). Rotate on a schedule and whenever someone who had access leaves; if a secret may have leaked, rotate twice to retire it immediately (why).

Keep responses small

DevStride reads at most 64 KB of your response; a larger one counts as a failure even with a 2xx status. An empty 204 No Content is ideal.

Watch the health signals

The failing and recovered emails go to everyone with Manage Webhooks: make sure that includes someone who will act on them. The red banner and the delivery log on the Webhooks page show what is failing and why. See Failing and recovered alerts.

Network and firewall notes

• Allow-list by signature, not by IP address. Deliveries do not come from a fixed, published set of IP addresses, so source-IP filtering is not a reliable way to accept DevStride and refuse everyone else. Authenticate each request by its signature.
• Your endpoint must be reachable from the public internet on HTTPS, with a certificate a standard client trusts (not expired, not self-signed, matching the host name).
• DevStride will not call private addresses. URLs whose host resolves to a private network, loopback, link-local or cloud-metadata address are refused when you save the endpoint and on every attempt. To deliver into a private network, expose a small public relay that verifies the signature and forwards inward.
• User-Agent: DevStride-Webhooks/1 identifies the requests in your logs and WAF rules. Anyone can send that header, so never treat it as proof.

Common problems

Privacy: erasure and redaction

Webhook deliveries are copies of your data, so DevStride's privacy tools reach them too:

• Erasing a requester (Anonymize…) deletes every stored item.created and comment.created delivery that carries that requester's tickets or words, including those of requesters merged into them, from the delivery log. Deliveries still waiting to be sent are deleted too, so they are never sent.
• Redacting a comment deletes that comment's stored comment.created deliveries the same way.

Once deleted, those deliveries can no longer be viewed or replayed. Status and SLA events carry only ids, and are not affected.