Email Marketing

Webhooks

We POST signed JSON to an HTTPS URL you choose. Register endpoints with the API or under Workspace → Webhooks.

Create an endpoint (API)

POST/api/v1/email/webhookswebhooks:write

curl

curl -sS https://api.thealtermeai.com/api/v1/email/webhooks \
  -H "Authorization: Bearer emk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-server.example/hooks/mcos","events":["message.sent","contact.created"]}'

Returns 201 with secret (whsec_…) once. List endpoints with GET /api/v1/email/webhooks (webhooks:read). Update with PATCH, delete with DELETE, or rotate the secret with POST …/rotate-secret.

Create an endpoint (dashboard)

Under Workspace → Webhooks, add an HTTPS URL, pick events, and copy the signing secret. Open Delivery log on that endpoint to inspect attempts and redeliver a past payload with the same bytes (dashboard only today).

Events

contact.created
contact.updated
contact.unsubscribed
contact.deleted
audience.subscribed
form.submitted
campaign.delivered
campaign.opened
campaign.clicked
campaign.bounced
campaign.complained
message.sent
message.delivered
message.bounced
message.complained
journey.enrolled
conversion.recorded

An unknown event name is rejected when you subscribe. At least one event is required.

message.sent fires when the provider accepts a transactional send. message.delivered, message.bounced, and message.complained follow provider feedback (same pipeline as campaign mail, different event names). Payloads include messageId, to, optional externalId and metadata from your API request. See Transactional email.

Payload

id	Delivery id.
type	One of the event names above.
version	API version of the payload.
createdAt	ISO 8601 timestamp.
organizationId	The organization the event belongs to.
data	Event-specific object.

Signature

Read the raw body before you parse it. The header X-MCOS-Signature looks like t=1710000000,v1=hex. v1 is the hex HMAC-SHA256 of the unix timestamp, a dot, and the raw body, signed with the endpoint secret.

Reject a timestamp more than five minutes from now. Compare the hex in constant time. A 2xx response marks the delivery successful. Anything else is retried. Redirects are not followed.

Other headers: X-MCOS-Webhook-Id, X-MCOS-Delivery, and X-MCOS-Webhook-Version. The user agent is MCOS-Webhooks/1.0.