---
title: "Create or replace your webhook"
method: PUT
path: "/webhook"
tags: ["Webhooks"]
---

# Create or replace your webhook

`PUT /webhook`

## Request

- Base URL: `https://api.treasuryspring.com/api/v1`
- URL: `https://api.treasuryspring.com/api/v1/webhook`
- Auth: HTTP bearer

Create your webhook, or replace its URL and types.

Creating it returns the signing secret, once. Replacing it keeps the secret, and resumes any
disabled delivery from where it stopped, so nothing is skipped. To change the secret, rotate it.

## Request body

- PutWebhookBody
  - `types` WebhookDataType[], required: What to deliver.
  - `url` string, required: HTTPS endpoint deliveries are POSTed to. Must be a public hostname, not an IP address; an international domain name must be given in its ASCII (xn--) form. Don't put credentials in it: verify each delivery's signature instead.

## Response `200`

The webhook, with its signing secret if it was just created

- PutWebhookResponse
  - `previousSecretExpiresAt` string, date-time, nullable: While a secret rotation is in progress, when deliveries stop also being signed with the previous secret; null otherwise.
  - `secret` string, nullable: Signing secret for verifying deliveries. Returned only when the subscription is created (201); store it securely. To change it, rotate it with POST /webhook/secret/rotate.
  - `status` WebhookStatus[], required: Delivery status for each type.
    - `disabledReason` 'FAILING' | 'GONE' | 'UNRESTRICTED_VISIBILITY': Why delivery stopped. FAILING: the endpoint failed every attempt for 24 hours. GONE: the endpoint answered 410 Gone. UNRESTRICTED_VISIBILITY: the account can now see every client's data, which webhooks do not serve.
    - `state` 'ACTIVE' | 'DISABLED', required
    - `type` 'EVENT', required: What a webhook delivers. Each type is delivered as its own ordered stream.
  - `types` WebhookDataType[], required: What is delivered.
  - `url` string, required: HTTPS endpoint deliveries are POSTed to.

## Other responses

- `201`: Webhook was created; the response includes its signing secret
- `403`: Forbidden. `unrestricted_event_visibility`: this API client can see every client's data, which webhooks do not serve.

## Changes

- **2026-10-20** `46eb173a4710`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/treasuryspring/apis/treasuryspring-public-api/changes/webhook/put.md)

---

[API](https://skmtc.dev/treasuryspring/apis/treasuryspring-public-api.md) - [All operations](https://skmtc.dev/treasuryspring/apis/treasuryspring-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/treasuryspring/apis/treasuryspring-public-api/revisions/ca7be51b723d?raw)