API referenceWebhooks
Register a webhook endpoint
Register a webhook endpoint
POST
/v1/projects/{projectId}/webhook-endpointsThe response contains secret exactly once; only an AES-256-GCM
wrapped copy is stored. The URL must be https:// and must not
resolve to a private, loopback, link-local, CGNAT, or cloud-metadata
address (SSRF defence). An API key needs the write scope. Rate limit: 60 requests per 60 s per caller.
Error codes: unauthorized (401), insufficient_scope (403),
not_found (404), invalid_url (400), invalid_body (400),
endpoint_limit_reached (409), webhooks_unconfigured (503).
Authentication
- apiKey — Project API key:
Authorization: Bearer vh_live_...(live mode) orAuthorization: Bearer vh_test_...(test mode). Keys carryreadand/orwritescopes.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string (Ulid) | Yes | — |
Request body
required
Content type: application/json
Schema: WebhookEndpointCreateRequest
{
"url": "https://example.com/webhooks/videohati",
"description": "Production receiver"
}Responses
| Status | Meaning |
|---|---|
201 | Endpoint registered. Store secret now; it is never shown again. |
400 | The request body or query failed validation. The per-operation description lists the exact error.code values. |
401 | No valid credential was presented. |
403 | The credential is valid but does not permit this action. The per-operation description lists the exact error.code values. |
404 | The resource does not exist or is not visible to this caller. |
409 | The request conflicts with the resource's current state. The per-operation description lists the exact error.code values. |
429 | Rate limit exceeded. |
Example request
{
"url": "https://example.com/webhooks/videohati",
"description": "Production receiver"
}Try it
POST
/v1/projects/{projectId}/webhook-endpointsTest mode only
API playground
Send a live request to api.videohati.com with a test-mode key.
This playground blocks vh_live_ keys. Use a key that starts with vh_test_ only; a request with a live key never leaves your browser.
The key is stored in your browser on docs.videohati.com only.