Register a webhook endpoint

POST

/webhook-endpoints

const url = 'https://mail.teamander.com/v1/webhook-endpoints';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"url":"https://example.com/webhooks/teamander","events":["email.delivered","email.bounced","email.complained"]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://mail.teamander.com/v1/webhook-endpoints \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "url": "https://example.com/webhooks/teamander", "events": [ "email.delivered", "email.bounced", "email.complained" ] }'

Subscribes a URL to delivery events. Returns a whsec_... signing secret once — use it to verify the X-Teamander-Signature header on incoming events. Max 10 endpoints per tenant.

Authorizations

bearerAuth

Request Body

application/json

object

url

required

string format: uri

<= 2048 characters

events

required

Array<string>

>= 1 items <= 9 items

Allowed values: email.sent email.delivered email.deferred email.bounced email.complained email.failed email.opened email.clicked email.unsubscribed

Example

{
  "url": "https://example.com/webhooks/teamander",
  "events": [
    "email.delivered",
    "email.bounced",
    "email.complained"
  ]
}

Responses

201

Endpoint created (secret shown once)

application/json

object

required

integer

url

required

string

events

required

Array<string>

active

required

boolean

secret

required

string

warning

required

string

Example

{
  "id": 1,
  "url": "https://example.com/webhooks/teamander",
  "events": [
    "email.delivered",
    "email.bounced"
  ],
  "active": true,
  "secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxx",
  "warning": "Save this signing secret now. It will not be shown again."
}

400

Validation failed

application/json

object

error

required

string

details

object

key

additional properties

nullable

Example

{
  "error": "Validation failed",
  "details": {}
}

401

Missing or invalid API key

application/json

object

error

required

string

message

string

Example

{
  "error": "Invalid API key"
}