---
title: "Register a webhook subscription"
method: POST
path: "/webhook_endpoints"
tags: ["Webhooks"]
---

# Register a webhook subscription

`POST /webhook_endpoints`

## Request

- Base URL: `https://dashboard.voidmob.com/api/v1`
- URL: `https://dashboard.voidmob.com/api/v1/webhook_endpoints`
- Auth: HTTP bearer

Registers an HTTPS URL to receive event deliveries. The response
includes the HMAC-SHA256 `signing_secret` **once** - store it securely;
it cannot be retrieved again. Use it to verify the
`X-VoidMob-Signature` header on every inbound delivery.

`event_types` accepts the literal `"*"` for all events, or any subset
of the typed enum. Max 20 endpoints per user.

## Request body

- CreateWebhookEndpointRequest
  - `url` string, uri, required
  - `event_types` WebhookEventType[]

## Response `201`

Endpoint registered. `signing_secret` is included exactly once.

- object
  - `success` true, required
  - `data` object, required
    - `endpoint` WebhookEndpointCreated, required
      - `id` string, required: Webhook endpoint identifier.
      - `url` string, uri, required
      - `event_types` WebhookEventType[], required
      - `enabled` boolean, required
      - `consecutive_failures` integer
      - `last_success_at` string, date-time, nullable
      - `last_failure_at` string, date-time, nullable
      - `created_at` string, date-time, required
      - `signing_secret` string, required: The HMAC-SHA256 signing secret for this endpoint. Returned **once** on creation and never again. Store it securely. Used to verify the `X-VoidMob-Signature` header on inbound webhook deliveries.

## Other responses

- `400`: 400 - Request failed validation.
- `401`: 401 - Authentication required.
- `429`: 429 - Rate limit exceeded. Retry after the indicated interval.

---

[API](https://skmtc.dev/voidmob/apis/voidmob-public-api.md) · [All operations](https://skmtc.dev/voidmob/apis/voidmob-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/voidmob/apis/voidmob-public-api/revisions/066023313ebe?raw)