API reference

Webhook endpoints

Register https endpoints for generation.completed, generation.failed, social_post.published, social_post.failed, credits.low. See the webhooks guide for payloads, retries and signature verification.

The webhook endpoint object

idstring
whk_ + 32 hex characters.
urlstring
Destination.
eventsstring[]
Subscribed events.
descriptionstring
Your label.
enabledboolean
Whether deliveries are sent.
created_atinteger
Unix ms.
secretstring
Signing secret (whsec_…). Returned only when created.

Create a webhook endpoint

POST/v1/webhooks

Scope: webhooksIdempotency-Key requiredReturns 201

The URL must be public https. Store secret — it is shown once.

Body

urlstringrequired
Public https URL.
eventsstring[]default: all events
generation.completed, generation.failed, social_post.published, social_post.failed, credits.low
descriptionstring
Up to 200 characters.

Errors

Code	When
`LIMIT_REACHED`	Plan allows 5 (Influencer) / 20 (Agency) endpoints.
`VALIDATION_ERROR`	Not a public https URL, or no valid event.

Request

curl -X POST https://api.oriorai.com/v1/webhooks \
  -H "Authorization: Bearer $ORIOR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/orior/webhooks",
  "events": [
    "generation.completed",
    "generation.failed"
  ],
  "description": "Production"
}'

const response = await fetch('https://api.oriorai.com/v1/webhooks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ORIOR_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "url": "https://example.com/orior/webhooks",
    "events": [
      "generation.completed",
      "generation.failed"
    ],
    "description": "Production"
  }),
})
const data = await response.json()
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`)

import os, uuid
import requests

response = requests.post(
    "https://api.oriorai.com/v1/webhooks",
    headers={"Authorization": f"Bearer {os.environ['ORIOR_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "url": "https://example.com/orior/webhooks",
        "events": ["generation.completed", "generation.failed"],
        "description": "Production",
    },
    timeout=60,
)
response.raise_for_status()
data = response.json()

Response · 201

Response

{
  "id": "whk_0a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "url": "https://example.com/orior/webhooks",
  "events": [
    "generation.completed",
    "generation.failed"
  ],
  "description": "Production",
  "enabled": true,
  "created_at": 1758620000000,
  "secret": "whsec_Zm9vYmFyYmF6cXV4cXV1eGNvcmdl"
}

List webhook endpoints

GET/v1/webhooks

Scope: webhooksReturns 200

All endpoints.

No parameters

Request

curl https://api.oriorai.com/v1/webhooks \
  -H "Authorization: Bearer $ORIOR_API_KEY"

const response = await fetch('https://api.oriorai.com/v1/webhooks', {
  headers: {
    Authorization: `Bearer ${process.env.ORIOR_API_KEY}`,
  },
})
const data = await response.json()
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`)

import os
import requests

response = requests.get(
    "https://api.oriorai.com/v1/webhooks",
    headers={"Authorization": f"Bearer {os.environ['ORIOR_API_KEY']}"},
    timeout=60,
)
response.raise_for_status()
data = response.json()

Response · 200

Response

{
  "data": [
    {
      "id": "whk_0a1b2c3d4e5f60718293a4b5c6d7e8f9",
      "url": "https://example.com/orior/webhooks",
      "events": [
        "generation.completed",
        "generation.failed"
      ],
      "description": "Production",
      "enabled": true,
      "created_at": 1758620000000
    }
  ]
}

Retrieve a webhook endpoint

GET/v1/webhooks/{id}

Scope: webhooksReturns 200

One endpoint (without its secret).

Path parameters

idstringrequired
Webhook ID.

Request

curl https://api.oriorai.com/v1/webhooks/whk_0a1b2c3d4e5f60718293a4b5c6d7e8f9 \
  -H "Authorization: Bearer $ORIOR_API_KEY"

const response = await fetch('https://api.oriorai.com/v1/webhooks/whk_0a1b2c3d4e5f60718293a4b5c6d7e8f9', {
  headers: {
    Authorization: `Bearer ${process.env.ORIOR_API_KEY}`,
  },
})
const data = await response.json()
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`)

import os
import requests

response = requests.get(
    "https://api.oriorai.com/v1/webhooks/whk_0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    headers={"Authorization": f"Bearer {os.environ['ORIOR_API_KEY']}"},
    timeout=60,
)
response.raise_for_status()
data = response.json()

Response · 200

Response

{
  "id": "whk_0a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "url": "https://example.com/orior/webhooks",
  "events": [
    "generation.completed",
    "generation.failed"
  ],
  "description": "Production",
  "enabled": true,
  "created_at": 1758620000000
}

Delete a webhook endpoint

DELETE/v1/webhooks/{id}

Scope: webhooksIdempotency-Key requiredReturns 200

Stops deliveries; pending retries are dropped.

Path parameters

idstringrequired
Webhook ID.

Request

curl -X DELETE https://api.oriorai.com/v1/webhooks/whk_0a1b2c3d4e5f60718293a4b5c6d7e8f9 \
  -H "Authorization: Bearer $ORIOR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

const response = await fetch('https://api.oriorai.com/v1/webhooks/whk_0a1b2c3d4e5f60718293a4b5c6d7e8f9', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.ORIOR_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
  },
})
const data = await response.json()
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`)

import os, uuid
import requests

response = requests.delete(
    "https://api.oriorai.com/v1/webhooks/whk_0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    headers={"Authorization": f"Bearer {os.environ['ORIOR_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    timeout=60,
)
response.raise_for_status()
data = response.json()

Response · 200

Response

{
  "id": "whk_0a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "object": "webhook",
  "deleted": true
}

Send a test event

POST/v1/webhooks/{id}/test

Scope: webhooksIdempotency-Key requiredReturns 200

Delivers a signed event with data.test: true to the endpoint, using its first subscribed event type.

Path parameters

idstringrequired
Webhook ID.

Request

curl -X POST https://api.oriorai.com/v1/webhooks/whk_0a1b2c3d4e5f60718293a4b5c6d7e8f9/test \
  -H "Authorization: Bearer $ORIOR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

const response = await fetch('https://api.oriorai.com/v1/webhooks/whk_0a1b2c3d4e5f60718293a4b5c6d7e8f9/test', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ORIOR_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
  },
})
const data = await response.json()
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`)

import os, uuid
import requests

response = requests.post(
    "https://api.oriorai.com/v1/webhooks/whk_0a1b2c3d4e5f60718293a4b5c6d7e8f9/test",
    headers={"Authorization": f"Bearer {os.environ['ORIOR_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    timeout=60,
)
response.raise_for_status()
data = response.json()

Response · 200

Response

{
  "object": "webhook_test",
  "webhook_id": "whk_0a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "event": "generation.completed",
  "sent": true
}

List deliveries

GET/v1/webhooks/{id}/deliveries

Scope: webhooksReturns 200

The last 50 deliveries (kept 30 days) with their outcome — useful when debugging an endpoint.

Path parameters

idstringrequired
Webhook ID.

Request

curl https://api.oriorai.com/v1/webhooks/whk_0a1b2c3d4e5f60718293a4b5c6d7e8f9/deliveries \
  -H "Authorization: Bearer $ORIOR_API_KEY"

const response = await fetch('https://api.oriorai.com/v1/webhooks/whk_0a1b2c3d4e5f60718293a4b5c6d7e8f9/deliveries', {
  headers: {
    Authorization: `Bearer ${process.env.ORIOR_API_KEY}`,
  },
})
const data = await response.json()
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`)

import os
import requests

response = requests.get(
    "https://api.oriorai.com/v1/webhooks/whk_0a1b2c3d4e5f60718293a4b5c6d7e8f9/deliveries",
    headers={"Authorization": f"Bearer {os.environ['ORIOR_API_KEY']}"},
    timeout=60,
)
response.raise_for_status()
data = response.json()

Response · 200

Response

{
  "data": [
    {
      "id": "dlv_3a9f…",
      "event_id": "evt_gen_7f3c9a1e2b4d4c8f9a0b1c2d3e4f5a6b_completed",
      "type": "generation.completed",
      "status": "delivered",
      "attempts": 1,
      "last_status": 200,
      "last_error": null,
      "next_attempt_at": null,
      "created_at": 1758620000000
    }
  ]
}