Create a webhook
Start sending events to a URL.
https://app.usenotix.dev/api/v1/webhooksNeeds a full access key. Sending access keys cannot call this. Key permissions lists the extra rules some calls have.
Start sending events to a URL. Pick the events in eventTypes (an empty list sends every event) and, optionally, limit them to some of your domains with domainIds.
The response is the only time Notix shows the signing secret (secret). Store it now and use it to check the X-Notix-Signature header of every event. If you lose it, rotate it.
Your plan sets how many webhooks a team can have; past that the answer is 403. A team can create 20 webhooks a minute.
The URL
Notix sends events from its own network, so the URL must be https with a public hostname. A raw IP address, localhost, a private or internal address, or a hostname that does not resolve answers 400 BAD_REQUEST. Notix checks the address again before every delivery.
Who can call it
A full access key created by a team admin, as on the dashboard. Every refusal is 403:
| Code | Why |
|---|---|
SCOPE_DENIED | The key is not a full access key (send-only, read-only or live AI). |
DOMAIN_PINNED | The key is limited to one domain. A webhook receives the events of every domain. |
FORBIDDEN | The key was made by a team member without admin rights, or before Notix recorded who made each key. Create a new key as a team admin. |
Adding a webhook, pointing one at a new URL or removing one emails the team's owner and admins, naming the key.
Body parameters
Where Notix sends events. Must be https with a public hostname: private addresses, localhost and raw IP addresses are refused.
At most 2,048 characters.
The events to send. An empty list means every event.
At most 500 characters.
Only send events for these domains. An empty list means every domain.
Headers
Bearer followed by your API key.
Errors
The URL is not a public https URL, or the body is not valid.
`SCOPE_DENIED`: the key is not a full access key (send-only, read-only or live AI). `DOMAIN_PINNED`: the key is limited to one domain. `FORBIDDEN`: the key was made by a team member without admin rights, or before Notix recorded who made each key (create a new key). `FORBIDDEN` also when the team's plan allows no more webhooks.
One of `domainIds` is not a domain of the team.
The team created 20 webhooks in the last minute.
Every error has the same shape. See all error codes.
curl -X POST "https://app.usenotix.dev/api/v1/webhooks" \
-H "Authorization: Bearer $NOTIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/webhooks/notix",
"eventTypes": [
"email.delivered",
"email.bounced"
],
"description": "Order system"
}'
import { Notix } from "notix-js";
const notix = new Notix(process.env.NOTIX_API_KEY);
const { data, error } = await notix.webhookEndpoints.create({
url: "https://example.com/webhooks/notix",
eventTypes: ["email.delivered", "email.bounced"],
description: "Order system",
});
// Shown only once: store it with your app's settings.
const signingSecret = data?.secret;
{
"id": "cm1x8f3k20001qz7v5b9d2e4a",
"url": "string",
"description": "string",
"status": "ACTIVE",
"eventTypes": [
"string"
],
"domainIds": [
1
],
"apiVersion": "string",
"consecutiveFailures": 1,
"lastFailureAt": "string",
"lastSuccessAt": "string",
"secretHint": "whsec_••••••••••••••••••••••••",
"createdAt": "string",
"updatedAt": "string",
"secret": "whsec_3f9c…"
}