Skip to Content
How-to guidesCreate a webhook endpoint

Create a webhook endpoint and rotate its secret

Let your own systems start work in Marshal. Your monitoring tool raises an alert, and a deputy starts investigating before anyone is paged. Your billing system sends an event, and a mission handles it. A webhook endpoint is a URL and a signing secret: your system sends signed events to the URL, and a deputy mission can start from them. For how to sign requests, see Sending Marshal a webhook.

Before you start

  • Role: admin or owner for an org-wide endpoint. Any member can create a personal endpoint.
  • Available when your administrator enables webhooks.

Steps

Create an endpoint

  1. Open the page:
    • Org-wide: organization menu in the top bar, Organization settings, then Webhooks. The tab is Receivers.
    • Personal: the account menu at the bottom of the left rail, Personal settings, then Webhooks. The tab is Your endpoints.
  2. On that tab, click Add endpoint.
  3. Enter a Name, for example billing. It must be unique among your endpoints.
  4. If the Owner field is shown, choose Org-wide (admins only), Just me, or a team you lead.
  5. Choose the Signature format that your sending system already uses. The default is Marshal (HMAC-SHA256 + timestamp). The others are Stripe, Standard Webhooks, Slack, Linear, Body only (no replay protection), and Shared token (no signature) for senders that offer only Bearer, Basic auth or a custom header. For Body only, you must tick “I understand a captured delivery can be replayed.” Shared token also asks you to confirm.
  6. If your sender makes its own secret, such as Stripe, Slack or Shopify, choose Paste the sender’s secret and paste it. It must be at least 32 characters. Otherwise leave the default and Marshal creates the secret. See Use the sender’s own secret.
  7. Click Create.
  8. A box titled Copy these now shows the Delivery URL and, when Marshal created it, the Signing secret. Copy them into your sending system. Click Done.

For step-by-step setup with Zendesk, Stripe and Slack, see Set up common senders.

A secret Marshal creates is shown once, and a pasted secret is never shown back. Treat the delivery URL as a secret too.

Rotate the secret

Rotate when a secret leaked, when a person who knew it left, or on a schedule. Only the owner of the endpoint can rotate it. For an org-wide endpoint, that means admins.

  1. Open the Receivers tab (org-wide) or the Your endpoints tab (personal) and click the endpoint’s card.
  2. In the side sheet, click Rotate secret.
  3. To use a secret your sender made, choose Paste the sender’s secret and paste it. Stripe and Slack endpoints always rotate this way.
  4. Leave the checkbox empty for a normal rotation. The old secret keeps working for 24 hours, so you can update your sender without losing events. Tick Revoke the old secret immediately, instead of keeping it for 24 hours only for an incident. The sender stops working until you update it.
  5. Click Rotate.
  6. If Marshal created the new secret, copy it from the box and put it in your sending system. Click Done.

The delivery URL does not change.

Check that it works

  1. Send a signed test request from your system.
  2. In the endpoint sheet, read Activity and Recent deliveries, or open the Deliveries tab.

A refused request shows a reason: Bad signature, Stale timestamp, or Unsupported format.

Delete an endpoint

In the endpoint sheet, click Delete and confirm. The URL and secret stop working for good. Any deputy trigger that listened to the endpoint stops firing.

What you should see

  • The new endpoint as a card under Custom endpoints, on the Receivers tab (org-wide) or the Your endpoints tab (personal).
  • After you send a good request, a delivery with the outcome Accepted on the Deliveries tab.
  • After rotation, the sheet shows Secret rotated with a time.

Next

Run a mission on a schedule or event: connect this endpoint to a mission so each event starts a run.

Use your own GitHub AppStart a run from a Linear issue