Runs examples for real against your account. Test keys only; kept in this tab, never stored on our side. Get a key
ZapSMTP / Docs / Webhooks

Update a webhook

PATCH/v1/webhooks/{id}

Update a webhook's URL, events, click-action filter or enabled state.

Requires a full-access live key; test keys get 403 test_key_restricted.

The response's disabled_reason reflects the value before the update (the store clears it on re-enable but the returned object is not reloaded).

Path parameters

idstringrequired
Webhook id

Body parameters

urlstring
Limits: absolute https:// URL
eventsstring[]
Limits: [] → 422 "select at least one event"; unknown type → 422 "unknown event type <x>" One of email.sent, email.delivered, email.delivery_delayed, email.bounced, email.complained, email.failed, email.opened, email.clicked, email.suppressed, email.received, thread.created, thread.replied, email.replied.
enabledboolean
Re-enabling clears disabled_reason. Disabling drops pending deliveries.
include_contentboolean
email.received carries the message: text, html, headers, and download links (valid 24 hours) for the attachments and the raw .eml; text and html are cut at 1 MB in total (truncated: true). Default false.
batchboolean
Send events up to 100 per request (or every second) as a JSON array, signed as one body; Zap-Event-Id is the batch id, each event keeps its own id. email.received with the full message still arrives alone. Default false.
filterobject
Narrows email.clicked to some click actions; other event types are not affected. Empty or absent: every click. Replaces the whole filter; {"actions": []} removes it.
Show 1 fields
actionsstring[]
Action names (lowercase letters, digits, _, . and -, starting with a letter or digit, up to 64 characters). The endpoint then receives email.clicked only for links with one of these actions. Limits: more than 50 → 422 invalid_parameter "filter.actions: at most 50"; a bad name → 422 invalid_parameter "filter.actions: <name> is not an action name"

Errors

restricted_api_keyHTTP 403
test_key_restrictedHTTP 403
test-mode keys can send test email and read, not change the account: use a live key
not_foundHTTP 404
webhook not found
invalid_parameterHTTP 422
PATCH/v1/webhooks/{id}
curl -X PATCH 'https://zapsmtp.xyz/v1/webhooks/019a1c55-0d6e-7f21-8b3a-5e9d4c7b2a10' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "enabled": true
}'
Set ZAP_API_KEY in your environment.
Response 200 OK
{
  "id": "019a1f22-6e7f-7091-8a2b-3c4d5e6f7a8b",
  "url": "https://acme.com/hooks/zapsmtp-v2",
  "events": [
    "email.delivered"
  ],
  "enabled": true,
  "disabled_reason": null,
  "created_at": "2026-10-20T12:00:00Z",
  "filter": {
    "actions": []
  }
}