Skip to content
AI Inbx
Esc
↑↓navigate↵open⌘Jpreview

Create a webhook endpoint

Registers an organization-wide endpoint and returns its signing secret exactly once, in the secret field: no later read shows it again. A secret that was lost, or has leaked, is replaced with POST /webhook-endpoints/{endpoint_id}/rotate-secret, which keeps the old one verifying for a grace period while you deploy the new one. subscriptions must name at least one event type. Setting payload to full puts the whole email on email.received and email.sent, as data.email, so a handler does not have to fetch it. Optional routing rules narrow delivery by sender or recipient: a matching block rule always wins, and an empty allow list means no opinion. The endpoint receives every space’s events, each stamped with its space_id.

POST/webhook-endpoints
Authorization
AuthorizationBearer token (API key) · headerrequired

Pass an AI Inbx API key as a Bearer token.

Header parameters
AIInbx-Workspacestring

Workspace id from GET /workspaces, for an OAuth token that reaches several.

min length 1
Request body
requiredapplication/json
urlstring<uri>required

Where deliveries are POSTed.

enabledboolean

Whether the endpoint receives deliveries.

default: true
subscriptionsstring[]required

The event types to deliver, at least one.

min items 1 · max items 100
routingobject[]

Rules that narrow delivery by sender or recipient, such as [{"effect":"block","field":"from","pattern":"..."}]. A matching block wins.

max items 100
Show properties
Array of object
effectstringrequired
Allowed:allowblock
fieldstringrequired
Allowed:fromtoeither
patternstringrequired
min length 1 · max length 320
max_concurrencyinteger

Deliveries in flight to this endpoint at once.

min 1 · max 128 · default: 16
payloadstring

How much of a message email.received and email.sent carry. summary is the addresses, subject and snippet; full adds data.email, the email as GET /emails/{id}?include=attachment_content returns it, so a handler has no second call to make. Every other event is the same either way, and an endpoint whose format is v1 cannot be full.

default: "summary"
Allowed:summaryfull
Responses
201

The endpoint was created; save its secret now.

idstringrequired
matches ^[a-z]+_[0-9a-f]{32}$
urlstring<uri>required
enabledbooleanrequired
formatstringrequired

Read-only. v1 marks an endpoint carried over from the previous aiinbx.com: it receives that system's bodies and can subscribe only to the events it had — email.received, email.delivered, email.bounced, email.complained, email.failed, email.opened, email.clicked. Endpoints created here are v2.

Allowed:v2v1
subscriptionsstring[]required
routingobject[]required
Show properties
Array of object
effectstringrequired
Allowed:allowblock
fieldstringrequired
Allowed:fromtoeither
patternstringrequired
min length 1 · max length 320
max_concurrencyintegerrequired
min -9007199254740991 · max 9007199254740991
payloadstringrequired

How much of a message email.received and email.sent carry. summary is the addresses, subject and snippet; full adds data.email, the email as GET /emails/{id}?include=attachment_content returns it, so a handler has no second call to make. Every other event is the same either way, and an endpoint whose format is v1 cannot be full.

Allowed:summaryfull
previous_secret_expires_atstring<date-time> | nullrequired
Show properties
Any of:
string<date-time>
string<date-time>
null
null
created_atstring<date-time>required
matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
updated_atstring<date-time>required
matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
secretstringrequired
400

The request is invalid.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
401

The API key is missing or invalid.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
402

The workspace has no plan (plan_required), or its plan's allowance is used up (allowance_reached).

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
403

The API key or token does not have the required scope, or the token is connected as an inbox and the operation is not one an inbox may use.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
404

The requested resource does not exist.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
409

The request conflicts with the resource's current state.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
413

The request body or attachments are too large.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
415

The request body is not JSON.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
422

The request body failed validation.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
429

The organisation's request budget is spent (too_many_requests), or an upstream mail provider is throttling (rate_limited).

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
500

An internal error occurred.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
502

An upstream mail provider failed.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
503

The service is temporarily unavailable.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
Request
import AIInbx from "aiinbx"

const aiinbx = new AIInbx()

const response = await aiinbx.webhookEndpoints.create({
  url: "https://app.example.com/webhooks/aiinbx",
  subscriptions: ["email.received", "email.bounced"],
})
Response
{
  "id": "string",
  "url": "http://example.com",
  "enabled": true,
  "format": "v2",
  "subscriptions": [
    "email.received"
  ],
  "routing": [
    {
      "effect": "allow",
      "field": "from",
      "pattern": "string"
    }
  ],
  "max_concurrency": -9007199254740991,
  "payload": "summary",
  "previous_secret_expires_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "secret": "string"
}