---
title: "Register a webhook"
method: POST
path: "/v1/webhooks"
---

# Register a webhook

`POST /v1/webhooks`

## Request

- Base URL: `https://api.hashlock.markets`
- URL: `https://api.hashlock.markets/v1/webhooks`
- Auth: HTTP bearer

Register a webhook. Events: quote.created, swap.agreed, swap.funded, secret.revealed, swap.settled, swap.refunded, swap.half_settled (omit = all). Returns the signing secret ONCE; deliveries are POSTed with X-Hashlock-Signature: sha256=HMAC-SHA256(secret, `${timestamp}.${body}`).

## Request body

- object
  - `url` string, uri, required: https only. Registration rejects an address LITERAL that is non-public, but does no DNS — a hostname resolving into a private range registers fine and then fails every delivery, visible only as lastStatus. Delivery resolves and re-checks at connect time, follows no redirects, and times out after 10s.
  - `events` string[]

## Response `201`

created — { webhook, secret }

- object

## Other responses

- `400`: error

---

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