---
title: "Register a webhook subscription"
method: POST
path: "/webhooks"
tags: ["Webhooks"]
---

# Register a webhook subscription

`POST /webhooks`

Creates a webhook subscription with a delivery URL and an optional list of event types to subscribe to (defaults to all when omitted). The response includes the generated signing secret, which is returned only once at creation time and cannot be retrieved later.

## Request body

- object
  - `url` string, uri, required
  - `eventTypes` string[]
  - `description` string

## Response `201`

Webhook created (secret shown once)

- object
  - `data` object, required
    - `id` string, uuid, required
    - `url` string, required
    - `eventTypes` string[], required
    - `state` 'ACTIVE' | 'DISABLED' | 'DELETED', required
    - `health` 'healthy' | 'failing' | 'blocked', required — System-observed delivery health. `blocked` endpoints are auto-disabled after sustained failure; PATCH state=ACTIVE to re-enable.
    - `blockedAt` string, nullable, required
    - `blockedReason` string, nullable, required
    - `signingEnabled` boolean, required
    - `description` string, nullable, required
    - `createdAt` string, required
    - `updatedAt` string, required
    - `secret` string, required — Signing secret — shown only once. Store it now.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `409` — Conflict
- `500` — Internal Server Error

---

[API](https://skmtc.net/mobilerun/apis/workflows.md) · [All operations](https://skmtc.net/mobilerun/apis/workflows/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mobilerun/workflows/revisions/1bc499aa8f99/schema)