Create an endpoint

POST/v1/webhooksKey scope write

Registers a URL that receives events as signed POST requests. The response carries the signing secret once: store it, because it cannot be read again, only rotated. Every delivery has the header Infrared-Signature: t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of <t>.<raw body> with the secret; reject a t older than 5 minutes.

Needs a key with the write scope. Authentication

curl https://api.useinfrared.com/v1/webhooks \
  -H "Authorization: Bearer $INFRARED_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/infrared",
    "description": "Marketplace backend",
    "event_types": ["moderation.completed", "queue_item.created"]
  }'

const response = await fetch("https://api.useinfrared.com/v1/webhooks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INFRARED_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/webhooks/infrared",
    description: "Marketplace backend",
    event_types: ["moderation.completed", "queue_item.created"],
  }),
});

const data = await response.json();

import os
import requests

response = requests.post(
    "https://api.useinfrared.com/v1/webhooks",
    headers={"Authorization": f"Bearer {os.environ['INFRARED_KEY']}"},
    json={
        "url": "https://example.com/webhooks/infrared",
        "description": "Marketplace backend",
        "event_types": ["moderation.completed", "queue_item.created"],
    },
)

data = response.json()

201 CreatedResponse

{
  "object": "webhook_endpoint",
  "id": "whe_2HLyVEWQelwo16welH16NM",
  "project_id": "prj_0TBAgHGtdMketrbltGFHuk",
  "url": "https://example.com/webhooks/infrared",
  "description": "Marketplace backend",
  "event_types": ["moderation.completed", "queue_item.created"],
  "status": "active",
  "api_version": "2026-09-01",
  "consecutive_failures": 0,
  "disabled_at": null,
  "disabled_reason": null,
  "last_delivery_at": null,
  "last_success_at": null,
  "created_at": "2026-10-08T09:28:59.023Z",
  "updated_at": "2026-10-08T09:28:59.023Z",
  "secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Request body

urlURLRequired

The URL to deliver to, up to 2,048 characters. It must use HTTPS and resolve to a public address.

descriptionstring

A note on what the endpoint is for, up to 500 characters.

event_typesarray of enums

The event types to deliver, up to 50. An empty array, the default, subscribes the endpoint to every event.

One ofmoderation.completedmoderation.failedqueue_item.createdqueue_item.allowedqueue_item.rejectedqueue_item.actionedqueue_item.reopenedauthor.blockedauthor.suspendedauthor.enabledauthor.trust_level_changedaction.executed

Returns

The new endpoint, including secret, with status 201.

201 CreatedA webhook endpoint object

Errors

403: plan_limit
The project already has as many webhook endpoints as the organisation's plan allows.
422: validation_error
url is not a valid HTTPS URL or resolves to a private, loopback or link-local address, an event type is unknown, or the body has an unknown key.

Every endpoint can also answer the errors any request can meet: a missing key, a rate limit, a malformed body. Errors

Something missing or unclear on this page? Write to support@useinfrared.com.