Create Webhook Endpoint

Registers a webhook endpoint to receive lifecycle events. The response includes the HMAC signing secret once — store it immediately; no later call returns it. If you lose it, delete the endpoint and create a new one.

Delivery starts with events created after the endpoint is registered — there is no backfill of earlier events. Link projects and subscribe before contracts you care about begin.

Requirements: webhooks:manage scope.

Request

urlstringbodyrequired

Delivery URL. Must be HTTPS (http is allowed for localhost only). Redirects are not followed.

eventTypesstring[]bodyrequired

At least one of: contract.started, contract.ended, project_link.created, project_link.removed, install.revoked, milestone.funded, milestone.budget_low, milestone.budget_depleted.

Response

webhookEndpointobject

The created endpoint: {id, url, eventTypes, status, createdAt, consecutiveFailures, disabledAt, disabledReason} — same shape as GET /webhook-endpoints/{endpointId}.

secretstring

HMAC-SHA256 signing secret for verifying deliveries. Shown only in this response.

messagestring

Reminder that the secret will not be shown again.

Errors

Status	code	Meaning
400	BAD_REQUEST	Body not valid JSON, url missing/not HTTPS, or eventTypes empty/contains an unknown type
401	UNAUTHORIZED	Missing, invalid, or revoked token
403	FORBIDDEN	Token lacks webhooks:manage
409	CONFLICT	Endpoint limit reached for this install

Request examples

curl

curl -sS -X POST https://app.opentrain.ai/api/partner/v1/webhook-endpoints \
  -H "Authorization: Bearer $OT_PARTNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-platform.example.com/webhooks/opentrain",
    "eventTypes": ["contract.started", "contract.ended", "install.revoked"]
  }'

Response examples

201

{
  "webhookEndpoint": {
    "id": "<ENDPOINT_ID>",
    "url": "https://your-platform.example.com/webhooks/opentrain",
    "eventTypes": ["contract.started", "contract.ended", "install.revoked"],
    "status": "ACTIVE",
    "createdAt": "2026-06-12T10:00:00.000Z",
    "consecutiveFailures": 0,
    "disabledAt": null,
    "disabledReason": null
  },
  "secret": "whsec_<SECRET>",
  "message": "Store the secret now — it is only returned once. Use it to verify the X-OpenTrain-Signature header on deliveries."
}