---
title: "Create Or Update Webhook"
method: POST
path: "/v1/webhooks"
tags: ["webhooks"]
---

# Create Or Update Webhook

`POST /v1/webhooks`

Register or update the webhook URL for this account.

If a webhook already exists, it will be updated.
A new secret is generated each time.

contextLimit: Number of recent messages to include in webhook payloads (0-50, default: 10).
Set to 0 to disable history in webhooks.

## Request body

- WebhookCreateRequest
  - `url` string, uri, required
  - `contextLimit` integer, nullable
  - `timeout` integer, nullable

## Response `200`

Successful Response

- WebhookResponse
  - `id` string, required
  - `url` string, required
  - `secret` string, required
  - `status` string, required
  - `contextLimit` integer, required
  - `timeout` integer, required
  - `createdAt` string, date-time, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/agentphone/apis/agentphone-api.md) · [All operations](https://skmtc.net/agentphone/apis/agentphone-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/agentphone/agentphone-api/versions/3f3aa65dcd20/schema)