---
title: "Register Webhook"
method: POST
path: "/v1/instances/{instance_id}/webhook-endpoints"
tags: ["Webhook Endpoints"]
---

# Register Webhook

`POST /v1/instances/{instance_id}/webhook-endpoints`

## Path parameters

- `instance_id` string, required

## Headers

- `Idempotency-Key` string — Optional key to safely retry this request without performing the action twice. Retrying with the same key and an identical body replays the original response; reusing a key with a different body returns an error. Keys are kept for 24 hours.

## Request body

- WebhookEndpointIn
  - `url` string, uri, required
  - `events` string[], required

## Response `200`

Create webhook endpoint

- WebhookEndpointOut
  - `id` string, required

## Other responses

- `400` — Possible error codes: `VALIDATION_FAILED`, `WEBHOOKS_LIMIT_REACHED`, `WEBHOOKS_URL_INVALID`. See the Error responses section for retry semantics.
- `401` — Possible error codes: `AUTH_UNAUTHORIZED`. See the Error responses section for retry semantics.
- `403` — Possible error codes: `AUTH_FORBIDDEN`. See the Error responses section for retry semantics.
- `429` — Possible error codes: `AUTH_RATE_LIMITED`. See the Error responses section for retry semantics.
- `500` — Possible error codes: `INTERNAL_ERROR`. See the Error responses section for retry semantics.

---

[API](https://skmtc.dev/blindpay/apis/blindpay-api.md) · [All operations](https://skmtc.dev/blindpay/apis/blindpay-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/blindpay/blindpay-api/revisions/470de27afb7b/schema)