---
title: "Register an https URL for signed incident events (Pro)."
method: POST
path: "/api/webhooks"
tags: ["Webhooks — Pro API key"]
---

# Register an https URL for signed incident events (Pro).

`POST /api/webhooks`

## Request

- Base URL: `https://outage.me`
- URL: `https://outage.me/api/webhooks`
- Auth: API key in header `x-tarantula-api-key`

We POST a signed challenge first; your URL must echo it (JSON {"challenge": ...} or the plain value) before deliveries start. The signing secret is returned once. Omit providers or events for all. Up to 5 per API key. See /llms.txt → Webhooks.

## Request body

- object
  - `url` string, required: https, public hostname.
  - `providers` string[]
  - `events` string[]

## Response `200`

Registered and verified (201) or pending verification (202)

- object
  - `webhook_id` string, required
  - `url` string
  - `providers` unknown
  - `events` string[]
  - `status` 'pending_verification' | 'active' | 'disabled', required
  - `failures` integer
  - `disabled_reason` string, nullable
  - `key_id` string
  - `created_at` integer, nullable
  - `last_delivery_at` integer, nullable
  - `last_result` string, nullable
  - `secret` string, required
  - `verification` string

## Other responses

- `400`: URL refused (not https, private address…) or unknown provider
- `403`: Not on Pro (the body carries upgrade_url) or no API key
- `409`: This URL is already active for this key
- `429`: 5 webhooks per API key

---

[API](https://skmtc.dev/outage/apis/outage-me-agent-api.md) · [All operations](https://skmtc.dev/outage/apis/outage-me-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/outage/apis/outage-me-agent-api/revisions/34d6abde73dd?raw)