Skip to content

Webhooks

Set up an endpoint

An endpoint is the web address Mestra sends events to. Only owners can add them.

Add an endpoint

  1. In Mestra, open Webhooks under Developer.
  2. On the Endpoints tab, choose Add endpoint.
  3. Enter the URL.
  4. Add a description if you like (up to 100 characters).
  5. Choose All events, or pick the event types you want.
  6. Save, then copy the signing secret.

The secret starts with whsec_. Mestra shows it once. Store it where your receiver can read it, such as an environment variable or a secrets manager. If you lose it, roll it.

The URL

  • It must start with https:// and use port 443.
  • It can’t contain a username or password.
  • It must be a public address. Mestra doesn’t send to private or internal addresses.
  • Mestra doesn’t follow redirects. Give the final address.
  • It can be up to 2,048 characters.

What Mestra sends

Each event arrives as a POST with the event as a JSON body and these headers:

Header Value
Content-Type application/json
User-Agent Mestra-Webhooks/1.0 (+https://withmestra.com/docs/webhooks/)
Mestra-Event-Id The event’s id, the same as in the body.
Mestra-Signature The signature.

Answer with any 2xx status within 10 seconds. That marks the event delivered. Any other answer, a timeout or a redirect counts as a failure, and Mestra will try again.

Change an endpoint

You can change an endpoint’s URL, description and event types, switch it off and on, or delete it. Switching an endpoint off stops further sends to it. Switching it back on doesn’t send the events it missed. To catch up, use the Events tab and Resend.

Roll the secret

Choose Roll secret on an endpoint to make a new one. You choose how long the old secret keeps working: not at all, or up to 24 hours. While both are valid, each event carries a signature for each, so your receiver can switch over without dropping events. See Verify signatures.

Roll a secret if it may have leaked.