Webhooks
Best practices
Check every signature
Reject anything that fails signature verification. Use the raw request body, a 5-minute tolerance and a constant-time compare.
Answer fast, work later
Answer with a 2xx status within 10 seconds, then do the work. Check the signature, store the event id and body, return 200, and let a background job do the rest. A slow answer counts as a failure and brings a retry.
Expect repeats
An event can arrive more than once: after a retry, after a resend, or when your answer was lost. Keep the ids you’ve handled and ignore ones you’ve seen. The Mestra-Event-Id header carries the id, so you can check before parsing the body.
Don’t rely on order
Events can arrive out of order, especially after a retry. A run.completed can show up before an earlier master.saved. Use created if you need to compare times, and fetch the object when you need the truth.
Fetch the object for the current state
An event says something happened and where to look. Fetch data.object.url for the current state instead of acting on the event alone. It’s always right, even if events arrived late or twice.
Keep the secret safe
Keep the secret in an environment variable or secrets manager, not in code or logs. If it may have leaked, roll it. See Set up an endpoint.
Handle unknown types
New event types and fields appear over time. Ignore types you don’t handle, and answer 2xx for them so they don’t retry.
Watch for a switched-off endpoint
If your receiver is down for 3 days, Mestra switches the endpoint off and emails the owners. See Retries and turning off. Fix the receiver, switch it on, then resend what you missed.