Skip to main content
POST
/
v1
/
webhook_endpoints
Register a webhook endpoint
curl --request POST \
  --url https://api.example.com/v1/webhook_endpoints \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "url": "https://api.acme.dev/aurous-webhook",
  "events": [
    "image.completed",
    "image.failed"
  ],
  "description": "Production webhook",
  "metadata": {
    "env": "prod",
    "team": "integrations"
  }
}
'
{
  "id": "we_01HXMQ7Z3K8Y2NABCDEFGHJKMN",
  "object": "webhook_endpoint",
  "url": "https://api.acme.dev/aurous-webhook",
  "events": [
    "image.completed"
  ],
  "secret_preview": "whsec_8jK...ABCD",
  "is_active": true,
  "consecutive_failures": 0,
  "last_success_at": "2026-05-04T01:00:00Z",
  "last_failure_at": "2026-05-04T00:55:00Z",
  "metadata": {},
  "created_at": "2026-05-03T14:00:00Z",
  "updated_at": "2026-05-03T14:00:00Z",
  "description": "Production webhook",
  "secret": "whsec_8jKpQ4nXabc1234abc..."
}

Documentation Index

Fetch the complete documentation index at: https://docs.aurous-labs.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
X-Api-Key
string
header
required

Your team API key (starts with al_live_ — legacy keys may start with og_).

Headers

​
Aurous-Version
string

Optional API version pin (YYYY-MM-DD). Defaults to your team's pinned version, or the system default 2026-05-15 for unauthenticated requests.

Pattern: ^\d{4}-\d{2}-\d{2}$
Example:

"2026-05-15"

Body

application/json
​
url
string
required

HTTPS endpoint to deliver events to. Plain http:// is rejected.

Maximum string length: 2048
Example:

"https://api.acme.dev/aurous-webhook"

​
events
string[]
required

Subscribed event types. Pass ["*"] to subscribe to every event currently in the v1.0 taxonomy (the wildcard is expanded at create time — future event additions do NOT auto-subscribe).

Example:
["image.completed", "image.failed"]
​
description
string

Optional human-readable label shown in the dashboard.

Example:

"Production webhook"

​
metadata
object

Optional structured metadata. Echoed verbatim on subsequent reads. Max 50 keys, string values <=500 chars.

Example:
{ "env": "prod", "team": "integrations" }

Response

Endpoint created

​
id
string
required

Opaque endpoint id (we_).

Example:

"we_01HXMQ7Z3K8Y2NABCDEFGHJKMN"

​
object
string
required
Example:

"webhook_endpoint"

​
url
string
required
Example:

"https://api.acme.dev/aurous-webhook"

​
events
string[]
required
Example:
["image.completed"]
​
secret_preview
string
required

Truncated preview of the active secret. Always present in dashboard hints.

Example:

"whsec_8jK...ABCD"

​
is_active
boolean
required
Example:

true

​
consecutive_failures
number
required

Consecutive 4xx/5xx/timeout/connect errors since the last successful delivery. The endpoint auto-disables at >=20 with no success in 24h (emits webhook.endpoint_disabled to other active endpoints + an email to the team owner).

Example:

0

​
last_success_at
object
required

Timestamp of the most recent 2xx delivery; null if never.

Example:

"2026-05-04T01:00:00Z"

​
last_failure_at
object
required

Timestamp of the most recent failed delivery (4xx/5xx/timeout/connect/TLS); null if never.

Example:

"2026-05-04T00:55:00Z"

​
metadata
object
required

Echoed customer metadata.

Example:
{}
​
created_at
string
required
Example:

"2026-05-03T14:00:00Z"

​
updated_at
string
required
Example:

"2026-05-03T14:00:00Z"

​
description
object
Example:

"Production webhook"

​
secret
object

Plaintext webhook secret. Returned EXACTLY ONCE on POST + /rotate_secret responses; null on every other read. Store on your side and use to verify the Aurous-Webhook-Signature header.

Example:

"whsec_8jKpQ4nXabc1234abc..."