Create a webhook endpoint

post/v1/webhook-endpoints

Registers a URL to receive the selected events. The response includes the endpoint's signing secret, shown once per create (and on an idempotent replay of that create); no other read returns it (roll it to get a new one). Verify deliveries with the X-Vojo-Signature header.

Idempotent replay: repeating this request with the same Idempotency-Key within 24 hours returns the original 201 response, including the original secret, with Idempotent-Replayed: true. The replay returns that original secret even if it has since been rolled or the endpoint deleted. The stored response keeps the secret encrypted at rest, never in plaintext.

Subscribing to verification.score: the endpoint is automatically given permissive filter settings: no band floor, no event minimums, backfill off. The event then fires for every play in the endpoint's scope that reaches its final score after the subscription is made, and never for plays that were already final (past plays are never replayed). attestConfigId in the event payload is the id of this auto-created config. Score filters are not configurable through /v1 yet; they may be added later as an additive change.

curl -X POST "https://api.vojo-media.com/v1/webhook-endpoints" \
  -H "Authorization: Bearer $VOJO_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Billing system",
  "url": "https://hooks.example.com/vojo",
  "enabled_events": [
    "verification.score",
    "wrapper.ready"
  ]
}'

const { data, error } = await api.POST("/v1/webhook-endpoints", {
  params: { header: { "Idempotency-Key": crypto.randomUUID() } },
  body: {
    name: "Billing system",
    url: "https://hooks.example.com/vojo",
    enabled_events: [
      "verification.score",
      "wrapper.ready",
    ],
  },
});
if (error) throw new VojoApiError(error);

Response 201

{
  "data": {
    "id": "cm1whe4r8t0001y2u6i9o3p5wa",
    "name": "Billing system",
    "url": "https://hooks.example.com/vojo",
    "enabled_events": [
      "verification.score",
      "wrapper.ready"
    ],
    "status": "active",
    "signed": true,
    "created_at": "2026-10-21T09:00:00Z",
    "updated_at": null,
    "secret": "whsec_3Jk9xQ2mN7pL4rT8vB1cZ6yW"
  },
  "meta": {}
}

Access

Authentication: Secret key or OAuth access token.
Scope: webhooks:write
User permission: developerAccess
Safe to retry: Send an Idempotency-Key.

Headers

Vojo-Organisationstring
The organisation this request acts on (org id). Required for oauth2 callers — a missing header returns 400 organisation_header_required; an org the user cannot access (a membership or an access grant, and granted to this OAuth client) returns 403 organisation_access_denied. Secret keys are bound to one org: the header may be omitted, and if sent it must match the key's org (else 403). Every query is scoped by the resolved org, never by an id in the body.
Vojo-Versionstring
Optional API version pin (a date). Overrides the version pinned on the secret key / organisation for this request. Echoed in the Vojo-Version response header. Within /v1 only additive changes ship, so most callers can omit it.
date
Idempotency-Keystring
Client-generated unique key (UUID v4 recommended) making this create safe to retry. A replay within 24 hours returns the stored response (with Idempotent-Replayed: true). Reusing a key with a different body returns 409 idempotency_key_reused.
8 to 255 characters

Request body

namestringRequired
1 to 120 characters
urlstringRequired
uri
enabled_eventsarray of stringRequired
at least 1 item

Response 201

Created

dataobjectRequired
A webhook endpoint plus its signing secret, returned only on create and roll.
Show 9 fields
- idstringRequired
- namestringRequired
- urlstringRequired
  HTTPS only.
  uri
- enabled_eventsarray of stringRequired
  Event types from the webhook catalogue (event reference). Unknown types return 422.
- statusstringRequired
  disabled = turned off by Vojo after repeated delivery failures; set active to resume.
  One of active, inactive, disabled
- signedbooleanRequired
  False only for legacy endpoints whose secret predates signing; roll the secret to start signing.
- created_atstringRequired
  date-time
- updated_atstring or nullRequired
  date-time
- secretstringRequired
  Signing secret. Shown only in this response.
metaobjectRequired

Response headers

Vojo-Versionstring
The API version (date) this response was rendered with — the request's Vojo-Version, else the key/org pin.
RateLimitstring
IETF RateLimit header: remaining quota in the current window, e.g. "default";r=97;t=42.
RateLimit-Policystring
IETF RateLimit-Policy header, e.g. "default";q=100;w=60. Portal OAuth clients get a higher tier.
Locationstring
URL of the created resource.
Idempotent-Replayedstring
true when this response is a stored replay of an earlier request with the same Idempotency-Key.

Errors

Every error is application/problem+json. Branch on its code.

400
Malformed request: invalid JSON, a bad cursor, a missing Vojo-Organisation for an OAuth caller, or an unknown Vojo-Version.
401
Missing, invalid, expired or revoked credential.
403
The caller is authenticated but not allowed: missing scope (insufficient_scope), missing Permissions flag (permission_denied), a client/installer persona on an operator endpoint (operator_access_required), or no access to the requested org (organisation_access_denied).
404
The resource does not exist, or belongs to another organisation. Cross-org ids always 404, never 403.
422
Well-formed request that failed validation. errors[] lists each failing field.
429
Rate limit exceeded for this principal. Back off for Retry-After seconds.
500
Unexpected server failure.