---
title: "Register a webhook for pushed findings"
method: POST
path: "/v1/webhook/configure"
tags: ["Account"]
---

# Register a webhook for pushed findings

`POST /v1/webhook/configure`

## Request

- Base URL: `https://api.relayshield.net`
- URL: `https://api.relayshield.net/v1/webhook/configure`
- Auth: one of:
  - API key in header `X-RS-API-KEY`
  - HTTP bearer

Free and unmetered. Registers one URL to receive findings (breach, infostealer, session hijack, ransomware victim listing, asset-intel matches) as they are detected, instead of polling. Post an empty `webhook_url` to clear the registration.

**Billing.** Free. This endpoint is not metered.

**Note.** Delivery is best-effort and fired inline with the originating call under a 6-second budget. A slow or failing endpoint never fails the API call that triggered it, so do not treat the webhook as a guaranteed-delivery channel -- poll for anything you must not miss.

## Request body

- object
  - `webhook_url` string, uri, required: An `https://` URL to receive findings. Send an empty string to clear.

## Response `200`

Success. `ok` is true and `data` holds the result.

- object
  - `ok` true, required
  - `data` object, required
    - `webhook_url` string: The registered URL, or an empty string after clearing.
    - `status` 'registered' | 'cleared': `cleared` when an empty URL was posted.

## Other responses

- `400`: `webhook_url` is non-empty but is not an http:// or https:// URL.
- `405`: Wrong HTTP method. Every endpoint is POST.
- `500`: Storing the registration failed.

---

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