Mailactor
API reference

Create a webhook

Each endpoint URL must be unique within the organization. For replacement without a gap, create a distinct receiver URL before deleting the old endpoint. Exact retries can recover the signing secret until signingSecretReplayUntil; after expiry they return 409 webhook_secret_replay_expired.

Required scope: webhook:manage.

POST/v1/webhooks

Authorization

tenantApiKey
x-api-key<token>

A scoped tenant key returned once by an operator. Never place it in URLs, logs, prompts, or client-side application code.

In: header

Header Parameters

idempotency-key*string
Match^[A-Za-z0-9._:-]+$
Length8 <= length <= 200

Request Body

application/json

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

Callbacks

# Set the API key and replace resource IDs with your saved IDs.# Generate once per logical action; preserve this key for retries.export IDEMPOTENCY_KEY="request-$(uuidgen)"curl --fail-with-body --silent --show-error -X POST \  "https://api.mailactor.com/v1/webhooks" \  -H "x-api-key: $MAILACTOR_API_KEY" \  -H "idempotency-key: $IDEMPOTENCY_KEY" \  -H "Content-Type: application/json" \  -d '{  "url": "https://your-app.example.com/webhooks/mailactor",  "events": [    "message.received"  ]}'

Response examples

Illustrative values; save the IDs and limits returned by your own requests.

HTTP 200

{
  "id": "whk_0123456789abcdef01234567",
  "url": "https://your-app.example.com/webhooks/mailactor",
  "events": [
    "message.received"
  ],
  "status": "active",
  "createdAt": "2026-09-08T12:00:00.000Z",
  "updatedAt": "2026-09-08T12:00:00.000Z",
  "signingSecret": "whsec_EXAMPLE_ONLY_DO_NOT_USE",
  "signingSecretReplayUntil": "2026-09-08T12:15:00.000Z",
  "replayed": true
}

HTTP 201

{
  "id": "whk_0123456789abcdef01234567",
  "url": "https://your-app.example.com/webhooks/mailactor",
  "events": [
    "message.received"
  ],
  "status": "active",
  "createdAt": "2026-09-08T12:00:00.000Z",
  "updatedAt": "2026-09-08T12:00:00.000Z",
  "signingSecret": "whsec_EXAMPLE_ONLY_DO_NOT_USE",
  "signingSecretReplayUntil": "2026-09-08T12:15:00.000Z",
  "replayed": false
}

HTTP 409

{
  "error": "webhook_secret_replay_expired",
  "message": "The signing-secret replay window for this idempotency key has expired"
}

HTTP 410

{
  "error": "webhook_endpoint_deleted",
  "message": "The webhook endpoint created by this idempotency key was deleted"
}