Endpoints

An endpoint is a webhook URL that receives parsed email in real time. Settings, Slack and Discord delivery, signing headers and retries.

An endpoint is a webhook destination: a URL that Inboundr POSTs to whenever mail arrives for an address, or a catch-all, routed to it. The endpoint holds the delivery settings: the signing secret, custom headers, timeout and number of attempts.

Creating an endpoint#

bash

curl https://inboundr.net/api/v1/endpoints \
  -H "Authorization: Bearer $INBOUNDR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production handler",
    "url": "https://api.example.com/hooks/inbound",
    "headers": { "X-Team": "growth" },
    "timeoutSeconds": 10,
    "maxAttempts": 5
  }'

The response includes a secret, prefixed whsec_, which is shown only once. Store it so you can verify signatures.

Settings#

urlstringbodyrequired

The HTTPS (or HTTP) URL to deliver to. It must resolve to a public host; private and internal addresses are rejected to prevent server-side request forgery.

headersobjectbody

Up to 10 custom headers sent with every delivery, for example an Authorization header for your own authentication. Reserved headers can't be overridden: Content-Type, the X-Inboundr-* headers, and their legacy X-Inbound-* spellings.

timeoutSecondsnumberbodydefault 10

Timeout for each request, from 1 to 30 seconds. A response that takes longer counts as a failed attempt.

maxAttemptsnumberbodydefault 5

Total delivery attempts, counting the first one and the retries, from 1 to 10. After the last one fails, the delivery is marked dead.

Slack and Discord#

An endpoint can also post a formatted notification to a Slack or Discord channel instead of your own server. Pass "type": "slack" or "type": "discord" when you create it, with url set to the channel's incoming-webhook URL. In Slack, that's under workspace settings, Incoming Webhooks; in Discord, under channel settings, Integrations, Webhooks.

Delivery, retries, timeoutSeconds and maxAttempts work the same as for a webhook. Two things differ: the body is a Slack or Discord message rather than raw JSON, and it isn't signed, because neither platform checks a signature.

Delivery, signing and retries#

Every delivery is signed with the endpoint's secret and carries these headers:

Header	Description
`X-Inboundr-Event`	Always `email.received`.
`X-Inboundr-Delivery-Id`	A unique ID shared by every attempt of this delivery.
`X-Inboundr-Signature`	`t=<unix>,v1=<hmac-sha256>`. Verify it with your secret.

The legacy X-Inbound-* headers are sent alongside these with the same values. They'll be removed once no endpoint depends on them.

Failed deliveries are retried with increasing delays (1 minute, 5 minutes, 30 minutes, then 2 hours) until one succeeds or maxAttempts runs out. The delivery is then marked dead and shown in the console. See Retries & delivery.

Redirects are not followed: a 3xx response is recorded as a failed attempt. Point the endpoint at the final URL.

Verify signatures

Validate the HMAC signature on every delivery.

Endpoints API

Create, list, update, test and delete endpoints.