Managing Webhooks

After you create a webhook (see Getting Started), you can edit it, turn it on or off, rotate its secret, or delete it. All of these actions are on the webhook detail page (/app/webhooks/{id}).

The webhook list

Open /app/webhooks to see every webhook on your account. The filter pills at the top of the page (All, Active, Inactive) narrow the list. Click a row to open the detail page.

Each row shows:

Column Description
Status An Active webhook accepts and delivers mail. An Inactive webhook rejects mail at SMTP time.
Name The label that you gave the webhook. Conduit generates one if you left the field blank.
Email Address The address that mail must go to.
Target URL The URL that Conduit POSTs the payload to.

Editing a webhook

On the detail page, click Edit. You can edit these fields:

Field Notes
Name Free text.
Email address Editable on a private domain. On the public domain the local part is fixed and read-only. See Public domain compared to custom domain.
Target URL Must be HTTPS.
Active The same as the Activate / Deactivate action below.
Security policy An optional SMTP security policy to attach.
Custom headers Optional extra HTTP headers on every outgoing request. Enter one Name: Value pair per line. Leave the field blank to send no custom headers. The X-Conduit-Signature header is reserved and cannot be overridden. See Custom headers.
Payload template An optional Go text/template. See Payload templates.
Rate limit The maximum number of emails that Conduit accepts per minute. Leave it blank, or enter 0, for no limit.

Activating and deactivating

Use the Activate / Deactivate button on the detail page to change the state. While a webhook is inactive, Conduit rejects mail at SMTP time with a permanent failure (550). The MTA of the sender then bounces the mail instead of a retry. Conduit keeps the existing delivery logs.

Deactivation is the safest way to pause traffic, for example while you debug your endpoint or move to a new URL. The webhook keeps its address, its secret and its history.

Rotating the secret

Conduit signs every delivery with the HMAC secret of the webhook. Rotate the secret if you believe that it leaked, or as part of routine credential hygiene.

  1. Open the webhook detail page.
  2. Click Rotate secret, then confirm the prompt.
  3. Copy the new secret immediately. Conduit shows it one time only, on the page that loads after the rotation.
  4. Update your endpoint to verify with the new secret.

CAUTION: The old secret stops working immediately. Any delivery that is in flight at the moment of the rotation carries the new signature. Update your endpoint first if you cannot accept a short gap in signature verification.

Deleting a webhook

Click Delete on the detail page and confirm. The deletion is permanent. It removes the webhook record, and it also deletes the delivery logs of that webhook. The email address becomes free, and another webhook can use it.

To stop mail for a short time only, deactivate the webhook instead of a deletion.

Next steps