Testing Webhooks

The Simulate action skips SMTP and asks Conduit to POST a synthetic payload directly to your endpoint. A real email through the SMTP gateway instead exercises the full inbound path, including any SMTP security policy on the webhook.

Both methods create a delivery log entry. The log view marks a simulated entry with SIM.

Simulate from the web UI

  1. Open the webhook detail page (/app/webhooks/{id}).
  2. Click Simulate in the sub-navigation and confirm.
  3. Conduit POSTs a synthetic payload to the target URL immediately.
  4. The result appears as a new entry in Recent Deliveries, and on the full Delivery Logs page with the SIM badge.

Simulate uses fixed defaults for the sender, the subject and the body. To set your own values for those fields, use the API.

Simulate through the API

POST /api/v1/webhooks/{id}/simulate
Authorization: Bearer <token>
Content-Type: application/json

{
  "from": "alerts@example.com",
  "subject": "Disk usage above 90%",
  "text": "Test alert from Conduit simulate"
}

All fields are optional. Conduit uses the defaults for a field that you omit. The response carries http_status, duration_ms, error, and simulated: true. For the full reference, see Simulate an email delivery.

Send a real test email

The Conduit SMTP gateway listens at mx.conduit.email on port 25 and supports STARTTLS. Address the email to the address of your webhook.

Quick test with swaks

swaks is available on most platforms (brew install swaks, apt install swaks):

swaks \
  --to webhook-01HX...@incoming.conduit.email \
  --from you@example.com \
  --server mx.conduit.email \
  --port 25 \
  --body "Hello from swaks"

Reading the SMTP response

The status code in the SMTP transcript gives the delivery outcome:

SMTP code Meaning
250 Your endpoint returned 2xx. The delivery succeeded.
450 Your endpoint returned 5xx, or it was unreachable. The sending MTA retries.
550 Your endpoint returned 4xx, or the webhook is inactive, or the SMTP policy rejected the message.

Your endpoint can override the SMTP code and the message. See SMTP Response Headers.

Which method to use

Use Simulate while you work on your endpoint, or when you want to exercise the delivery path without an RFC 5322 message.

Send a real email for one of these reasons:

  • You must test an attached SMTP security policy.
  • You want to make sure that the DNS and MX records deliver to Conduit.
  • You must test how your endpoint parses a specific mail format from a real sender.

Next steps