Skip to content

MailerAddWebhook

POST mailer/webhook

Creates a public callback URL for a provider profile. This is how a profile with deliveryUpdateBy: "WEBHOOK" receives delivery events: deliveries, bounces, complaints, opens and clicks.

Bounces and complaints are the important ones — they feed the suppression list automatically, and without them the domain reputation degrades silently.

Access Control

Allowed role: admin, within the brand of the caller.

Request

POST https://{broker_domain}/mailer/webhook
{
  "name": "Postmark events",
  "profileId": 3,
  "status": "ENABLED",
  "secretKeyAutoGenerate": true
}

{
  "command": "MailerAddWebhook",
  "extID": "1",
  "data": {
    "name": "Postmark events",
    "profileId": 3,
    "status": "ENABLED",
    "secretKeyAutoGenerate": true
  }
}

const res = await platform.MailerAddWebhook({
  name: "Postmark events",
  profileId: 3,
  status: "ENABLED",
  secretKeyAutoGenerate: true
});

Request Data

Field Type Required Description
name string Yes Webhook name for the UI
description string No Free-form note
profileId int Yes Provider profile the events belong to
status enum Yes ENABLED or DISABLED
secretKey string No Signing secret, 10..255 characters. Use the provider value when the provider issues it
secretKeyAutoGenerate bool No Generate the secret instead of passing one
events array No Event names to accept. Empty means every event the adapter understands

Behavior

  • The full public URL is composed by the integration domain: the module returns the path, because only the deployment knows the host.
  • The uuid is stable for the lifetime of the webhook — it is configured on the provider side, so regenerating it would silently stop the events.
  • Signature verification is adapter-specific: SendGrid signs with ECDSA, Mailgun with an HMAC over timestamp and token, SES posts SNS messages with a certificate URL. The secret stored here is what those checks use.

Response Data

A webhook can be created for any profile of the brand — the mode is checked when an event arrives. A profile that is not in WEBHOOK mode answers incoming events with PROFILE_NOT_IN_WEBHOOK_MODE.

{
  "id": 2,
  "brand": "default",
  "profileId": 3,
  "uuid": "9f2a1c7d4b6e",
  "name": "Postmark events",
  "description": null,
  "secretKey": "s3cr3t-generated-value",
  "events": [],
  "status": "ENABLED",
  "path": "/mailer/handleWebhooks/9f2a1c7d4b6e",
  "createdAt": "2026-08-24 13:55:20"
}

Errors

Code Error Description
400 VALIDATION_ERROR Secret is shorter than 10 characters, or a required field is missing
400 PROVIDER_IS_DISABLED The provider behind the profile is disabled
404 PROFILE_NOT_FOUND Profile not found in the brand
404 PROVIDER_NOT_FOUND The profile points at a provider that no longer exists