Create a webhook endpoint

POST https://api.veriko.mx/v1/webhooks

Audience: public
Permission: webhooks:create

Registers a new HTTPS endpoint for receiving event notifications. The signing secret is returned exclusively in this response and cannot be retrieved later — store it securely. Validate the incoming body with HMAC-SHA256 against the X-{Brand}-Signature: sha256=<hex> header. After creating the endpoint, send a synthetic delivery with POST /v1/webhooks/{id}/test to confirm the receiver returns 2xx before enabling production traffic.

Parameters
Parameter	Type	Required	Description
`url`	string (uri) (?–2048)	required	HTTPS URL that receives the webhook. Must be HTTPS.
`events`	array<string> (items: 1–10)	required	Events the endpoint subscribes to (1–10).
`description`	string (?–255)	optional	Descriptive label for the endpoint.

Request

cURLPython•JavaScript•PHP•

curl -X POST 'https://api.veriko.mx/v1/webhooks' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://webhook.example.com/platform",
    "events": [
      "validation.completed",
      "validation.failed",
      "validation.error",
      "billing.payment_succeeded",
      "billing.payment_failed"
    ],
    "description": "Webhook plataforma completo"
  }'

Python example — coming soon.

JavaScript example — coming soon.

PHP example — coming soon.

**Response 201** `WebhookEndpoint` — Endpoint created. The `secret` field only appears in this response; store it securely to verify `X-{Brand}-Signature: sha256=<hex>` signatures (HMAC-SHA256 over the body).
Field	Type	Description
`type` *	`string`
`id` *	`string (uuid)`	Endpoint identifier.
`attributes` *	`object`	Canonical webhook endpoint attributes (receiver URL, subscribed events, status, and secret).
`url`	`string (uri)`	HTTPS receiver URL. Production rejects plain HTTP, URLs resolving to private IPs (SSRF), and URLs `>2048` chars.
`events`	`array`	List of subscribed events. Maximum 10.
`description`	`string \| null` nullable	Free-form endpoint label.
`status`	`string`	`active` receives deliveries. `disabled` was manually paused. `auto_disabled` was disabled by the platform after exceeding `webhooks.auto_disable_threshold` consecutive failures.
`consecutive_failures`	`integer`	Consecutive failures counter. Resets on a success.
`last_delivery_at`	`union`	UTC timestamp of the last delivery attempt (any status). `null` when the endpoint hasn't received any delivery yet.
`secret`	`string`	Shared secret for signature verification. Only present in the create and rotate-secret responses; omitted from every other response.
`secret_hint`	`string`	Last 4 chars of the secret prefixed with `...`. Present on any response where the full `secret` is hidden.
`created_at`	`string (date-time)`	ISO 8601 timestamp in UTC with explicit `Z` suffix. Example: `"2026-05-01T05:14:38Z"`. Every datetime field uses this shape. The descriptor at `meta.datetime` makes the contract runtime-assertable.
`updated_at`	`string (date-time)`	ISO 8601 timestamp in UTC with explicit `Z` suffix. Example: `"2026-05-01T05:14:38Z"`. Every datetime field uses this shape. The descriptor at `meta.datetime` makes the contract runtime-assertable.

**Response status codes** `POST /v1/webhooks`
Status	Class	Description	Body
201	`2xx`	Endpoint created. The `secret` field only appears in this response; store it securely to verify `X-{Brand}-Signature: sha256=<hex>` signatures (HMAC-SHA256 over the body).	No body
401	`4xx`	Authentication is required or the provided credentials are invalid.	`ErrorResponse`
403	`4xx`	Permisos insuficientes	`ErrorResponse`
422	`4xx`	Invalid data. Possible codes: `webhook_url_required`, `webhook_url_too_long`, `webhook_url_invalid_format`, `webhook_url_not_https`, `webhook_events_required`, `webhook_events_too_many`, `webhook_event_invalid`, `webhook_limit_reached`.	`ErrorResponse`
429	`4xx`	Rate limit exceeded	`ErrorResponse`

**Errors from `POST /v1/webhooks`**
Status	Code	Detail
401	`unauthorized`	Invalid or missing authentication credentials. Envelope meta.request_id `c4d5e6f7a8b9`
403	`forbidden`	You do not have permission to access this resource. Envelope meta.request_id `d5e6f7a8b9c0`
429	`rate_limit_exceeded`	Rate limit exceeded. Try again in 45 seconds. Envelope meta.request_id `f7a8b9c0d1e2` Response headers `Retry-After` : integer — Seconds to wait before retrying. Matches the endpoint's rate-limit window (typically 60s for list endpoints, 1-5s for in-flight idempotent operations). `X-RateLimit-Limit` : integer — Configured request cap for this bucket (emitted only on 429). `X-RateLimit-Remaining` : integer — Requests remaining in the current window — always 0 at the moment of the 429 (emitted only on 429). `X-RateLimit-Reset` : integer — Absolute Unix epoch (seconds) when the window resets. Emitted only on 429, alongside Retry-After. Per-endpoint overrides exist (e.g. `rate_limited_login`).