---
title: "Subscribe a webhook URL"
method: POST
path: "/webhooks/subscribe"
tags: ["Webhooks"]
---

# Subscribe a webhook URL

`POST /webhooks/subscribe`

## Request

- Base URL: `https://tickerz.com/api/v1`
- URL: `https://tickerz.com/api/v1/webhooks/subscribe`
- Auth: none declared

## Request body

- WebhookSubscribeRequest
  - `email` string, email, required
  - `url` string, uri, required: HTTPS only

## Response `200`

Received. A new email gets its signing secret once. An email already on file is left as it is and gets the same ok answer without a secret, so the endpoint does not say who is subscribed.

- WebhookSubscribeResponse
  - `ok` boolean
  - `confirmed` boolean
  - `id` string, uuid
  - `secret` string: HMAC-SHA256 key; shown once
  - `verify` string

## Other responses

- `400`: invalid_json | invalid_email | invalid_url | challenge_failed
- `403`: cross_site: the request came from another site
- `415`: not_json: content-type must be application/json
- `429`: rate_limited: five signups per address per ten minutes
- `500`: save_failed | confirm_failed
- `503`: unavailable: the database is not connected or could not be read

---

[API](https://skmtc.dev/tickerz/apis/tickerz-api.md) · [All operations](https://skmtc.dev/tickerz/apis/tickerz-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tickerz/apis/tickerz-api/revisions/075e6b98557d?raw)