Create a Webhook Endpoint

Webhook is currently in Beta. APIs, fields, and behavior may change in future versions.

POST /api/v1/forward/webhook/endpoints

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <PAT or administrator SAT>`
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	Optional idempotency key. Reuse a key only for the same request.

Body parameters

Field	Type	Required	Description
`url`	string	Yes	HTTP or HTTPS receiver URL. HTTPS is recommended in production.
`description`	string	No	Purpose of the Endpoint.
`events`	string[]	Yes	Event subscriptions. Must contain at least one item. Accepts `` or a specific `namespace.name` event; prefix wildcards such as `forward.` are not supported. See Supported public events for full event names and triggers. Only events in that catalog have a Forward delivery contract.
`metadata`	object	No	Custom string key-value pairs.

Example request

curl -s -X POST 'https://api.qoder.com/api/v1/forward/webhook/endpoints' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: webhook-endpoint-production' \
  -d '{
    "url": "https://example.com/webhooks/qoder",
    "description": "Schedule notifications",
    "events": [
      "forward.schedule.created",
      "forward.schedule.archived",
      "forward.schedule_run.succeeded",
      "forward.schedule_run.failed"
    ],
    "metadata": {
      "environment": "production"
    }
  }'

Example response

HTTP 201 Created

{
  "id": "e149c233-1234-4abc-8def-1234567890ab",
  "url": "https://example.com/webhooks/qoder",
  "description": "Schedule notifications",
  "events": [
    "forward.schedule.created",
    "forward.schedule.archived",
    "forward.schedule_run.succeeded",
    "forward.schedule_run.failed"
  ],
  "metadata": {
    "environment": "production"
  },
  "active": true,
  "signing_secret": "whsec_BASE64_ENCODED_SECRET",
  "created_at": "2026-09-01T08:00:00Z"
}

Response fields

Field	Type	Description
`id`	string	Endpoint ID. Store it as an opaque string.
`url`	string	Event receiver URL.
`description`	string	Endpoint description.
`events`	string[]	Current event subscriptions.
`metadata`	object	Custom metadata. The response may include fields maintained by the platform.
`active`	boolean	Whether the Endpoint is enabled. New Endpoints are `true`.
`signing_secret`	string	Secret used to verify Webhook signatures. Returned only in this response.
`created_at`	string	Creation time, in RFC 3339 format.

Securely store signing_secret immediately. List, get, and update APIs do not return it again.

Errors

HTTP	Type	Trigger
`400`	`invalid_request_error`	The URL, event list, metadata, or request body is invalid.
`401`	`authentication_error`	Authentication is missing, invalid, or expired.
`403`	`permission_error`	The current token cannot manage Webhooks.
`409`	`conflict_error`	The idempotency key conflicts with an existing request, or the Endpoint limit has been reached.
`413`	`invalid_request_error`	The request body is too large.
`429`	`rate_limit_error`	The request rate limit has been reached.

Create a Webhook Endpoint

Headers

Body parameters

Example request

Example response

Response fields

Errors

Send a test event

Receive Webhook events

​Headers

​Body parameters

​Example request

​Example response

​Response fields

​Errors

​Related

Send a test event

Receive Webhook events

Headers

Body parameters

Example request

Example response

Response fields

Errors

Related