Register a webhook endpoint (POST /v1/webhooks)

POST/v1/webhooks

Registers an endpoint and immediately proves it with a signed webhook.test event. The endpoint is active when the test was acknowledged with a 2xx and failed when it was not; a failed endpoint receives no events until it is deleted and re-registered. The secret appears in this response and nowhere else, ever. Owner or admin only: a MEMBER's key or connection gets 403 forbidden.

Price

Free.

Request body

application/json

object

urlstringrequiredformat uriHTTPS only; private ranges are refused.
descriptionstring

Responses

201 Created

{ webhook, secret, test_delivery }.

object

webhookobjectrequired
- idstringrequired
- urlstringrequired
- statusstringrequiredone of pending, active, failed, disabled
- descriptionstringrequirednullable
- secret_prefixstringrequiredThe first characters of the signing secret, to tell two apart.
- previous_secret_expires_atstringrequirednullable
- created_atstringrequired
- activated_atstringrequirednullable
- last_delivery_atstringrequirednullable
secretstringrequiredShown once, here and nowhere else. Store it now.
test_deliveryobjectrequiredThe signed webhook.test event that decided activation.
- idstringrequired
- event_idstringrequiredStable across replays, so a receiver can de-duplicate.
- event_typestringrequiredone of run.completed, tracker.changed, webhook.test
- statusstringrequiredone of pending, delivered, failed
- attemptsintegerrequired
- response_statusintegerrequirednullable
- errorstringrequirednullable
- run_idstringrequirednullable
- tracker_idstringrequirednullable
- change_report_idstringrequirednullable
- replay_ofstringrequirednullable
- created_atstringrequired
- last_attempt_atstringrequirednullable
- delivered_atstringrequirednullable
- failed_atstringrequirednullable

201 · `{ webhook, secret, test_delivery }`.

{
  "webhook": {
    "id": "whe_6d2f10ab44",
    "url": "https://hooks.example.com/shortsintel",
    "status": "active",
    "description": "production receiver",
    "secret_prefix": "whsec_a1b2c3",
    "previous_secret_expires_at": null,
    "created_at": "2026-09-08T09:14:02.418Z",
    "activated_at": "2026-09-08T09:14:03.006Z",
    "last_delivery_at": "2026-09-08T09:14:03.006Z"
  },
  "secret": "whsec_9Qk3Tn7f2xLd0aZmVbYpRc8sHu6WjEg4",
  "test_delivery": {
    "id": "whd_51c8b0f7e3",
    "event_id": "evt_kZ8Qw3n1TfLd0aZmVbYpRc",
    "event_type": "webhook.test",
    "status": "delivered",
    "attempts": 1,
    "response_status": 200,
    "error": null,
    "run_id": null,
    "tracker_id": null,
    "change_report_id": null,
    "replay_of": null,
    "created_at": "2026-09-08T09:14:02.911Z",
    "last_attempt_at": "2026-09-08T09:14:03.006Z",
    "delivered_at": "2026-09-08T09:14:03.006Z",
    "failed_at": null
  }
}

400 Bad Request

invalid_request for http, private ranges or an unresolvable host.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose.

typestringrequired
titlestringrequired
statusintegerrequired
codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_errorStable machine-readable code.
detailstring

400 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "`url` must be https and must not resolve to a private address."
}

401 Unauthorized

missing_authorization, invalid_key, key_revoked or invalid_token.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose.

typestringrequired
titlestringrequired
statusintegerrequired
codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_errorStable machine-readable code.
detailstring

401 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/invalid_key",
  "title": "Invalid key",
  "status": 401,
  "code": "invalid_key",
  "detail": "That API key does not exist. Keys look like `sk_live_...` and are created in the console."
}

403 Forbidden

forbidden — the key's or connection's user is a MEMBER; only an owner or admin manages webhooks.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose.

typestringrequired
titlestringrequired
statusintegerrequired
codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_errorStable machine-readable code.
detailstring

403 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "code": "forbidden",
  "detail": "Only an owner or admin can manage webhooks."
}

409 Conflict

webhook_limit_exceeded at 5 endpoints.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose.

typestringrequired
titlestringrequired
statusintegerrequired
codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_errorStable machine-readable code.
detailstring

409 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/webhook_limit_exceeded",
  "title": "Webhook limit exceeded",
  "status": 409,
  "code": "webhook_limit_exceeded",
  "detail": "You already have 5 endpoints. Delete one before registering another.",
  "limit": 5,
  "active": 5
}

Request samples

curl -X POST "https://www.shortsintel.com/v1/webhooks" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/shortsintel"}'

const response = await fetch(
  "https://www.shortsintel.com/v1/webhooks",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer sk_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "url": "https://example.com/hooks/shortsintel"
    }),
  },
);

if (!response.ok) {
  throw new Error(`ShortsIntel ${response.status}`);
}

const data = await response.json();

import requests

response = requests.post(
    "https://www.shortsintel.com/v1/webhooks",
    headers={
        "Authorization": "Bearer sk_live_YOUR_KEY",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://example.com/hooks/shortsintel",
    },
)
response.raise_for_status()

data = response.json()

Webhooks: The events we send, how to verify a signature, what happens when your endpoint is down, and how to rotate a secret.

Price

Request body

Responses

201 Created

400 Bad Request

401 Unauthorized

403 Forbidden

409 Conflict

Request samples

Related guides