---
title: "Register webhook endpoint"
method: POST
path: "/webhooks"
tags: ["Webhooks"]
---

# Register webhook endpoint

`POST /webhooks`

## Request

- Base URL: `https://api.woopsocial.com/v1`
- URL: `https://api.woopsocial.com/v1/webhooks`
- Auth: HTTP bearer

Registers a URL to receive webhook events for the specified event types.

The response includes a `signingSecret` (base64-encoded, 32 bytes) that is
returned **once only**. Use it to verify the `X-Woop-Signature` header on
incoming webhook payloads.

**Signature format:** `t=<unix>,v1=<hmac-sha256-hex>`
**Signed payload:** `<unix>.<json-body>`

## Request body

- CreateWebhookEndpointRequest
  - `eventTypes` WebhookEventType[], required: Webhook event types this endpoint should receive.
  - `url` string, required: The HTTPS URL to POST webhook events to.

## Response `201`

Webhook endpoint registered.

- WebhookEndpoint
  - `createdAt` string, date-time, required
  - `eventTypes` WebhookEventType[], required
  - `id` string, required: Webhook endpoint identifier (int64 as string).
  - `signingSecret` string: Base64-encoded 32-byte signing secret. Returned once on creation only.
  - `url` string, required

## Other responses

- `422`: Validation error (unknown event type, empty url, etc.).
- `429`: Too many requests are already in progress for this API key.

---

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