---
title: "Register a delivery webhook"
method: POST
path: "/v1/monitor/webhook"
tags: ["Monitoring (Registry Watch)"]
---

# Register a delivery webhook

`POST /v1/monitor/webhook`

## Request

- Base URL: `https://jp-verify.obolpay.xyz`
- URL: `https://jp-verify.obolpay.xyz/v1/monitor/webhook`
- Auth: API key in header `X-API-Key`

Register a delivery webhook for this caller. Body ``{"url": "https://…"}``. The URL is
SSRF-guarded (https only; no private/loopback/link-local/metadata targets) — a bad URL is
refused FREE. (Outbound delivery itself is a separate mechanism; this endpoint is CRUD +
validation only.) Requires ``X-API-Key`` (1.4.0). Metered. Opt-in ``Idempotency-Key``
header: a retry with the same key + body replays the first response instead of
re-metering.

## Headers

- `X-API-Key` string

## Request body

- object: ``POST /v1/monitor/webhook`` body.
  - `url` string, required: https:// delivery endpoint (SSRF-guarded: no private/loopback/link-local/metadata targets)

## Response `200`

Successful Response

- unknown

## Other responses

- `400`: Malformed input — refused before metering; nothing was charged.
- `401`: No API key (required on every /v1/monitor/* operation since release 1.4.0 — refused before any body read or metering, nothing was charged), or an unknown, inactive, or expired key.
- `413`: Request body over the size cap — refused before it was buffered or parsed; nothing was charged.
- `422`: Validation Error
- `429`: Quota exceeded for the caller's tier.
- `503`: The register, or an optional feature, is unavailable or not configured on this deployment. A register 503 (since 1.4.1) also carries the mirror's `data_as_of` with the source fields — `source_latest_diff_date` (the newest 差分 the NTA 公表サイト listed when the sync last read it), `source_checked_at`, `source_gap_business_days` and `freshness.rule` (`stale` here) — so a caller can tell a mirror that is behind its source (`data_date` older than `source_latest_diff_date`) from a source that has not published (equal, but `source_checked_at` older than `freshness.source_check_max_hours`); `data_as_of` is null when the mirror is absent. Nothing was charged.

---

[API](https://skmtc.dev/obolpay/apis/jp-verify.md) · [All operations](https://skmtc.dev/obolpay/apis/jp-verify/llms.txt) · [OpenAPI document](https://skmtc.dev/obolpay/apis/jp-verify/revisions/bf8851690df0?raw)