Skip to main content

Create a Webhook Endpoint

Register a Webhook receiver URL and the events to subscribe to.

Webhook is currently in Beta. APIs, fields, and behavior may change in future versions.
POST /api/v1/forward/webhook/endpoints

Headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT or administrator SAT>
Content-TypeYesapplication/json
Idempotency-KeyNoOptional idempotency key. Reuse a key only for the same request.

Body parameters

FieldTypeRequiredDescription
urlstringYesHTTP or HTTPS receiver URL. HTTPS is recommended in production.
descriptionstringNoPurpose of the Endpoint.
eventsstring[]YesEvent 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.
metadataobjectNoCustom string key-value pairs.
To receive the results of creating, querying, updating, or archiving Schedules through natural language, add the required management tool result events to events. For example, use forward.schedule.queried for successful queries, forward.schedule.updated for changes that take effect, and forward.schedule.update_failed for failed updates. No notification is sent when the update result is unchanged; calling the HTTP Update Schedule API directly does not produce an update success event either. For failures only, subscribe to forward.schedule.create_failed, forward.schedule.query_failed, forward.schedule.update_failed, and forward.schedule.archive_failed.

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.updated",
      "forward.schedule.update_failed",
      "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.updated",
    "forward.schedule.update_failed",
    "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

FieldTypeDescription
idstringEndpoint ID. Store it as an opaque string.
urlstringEvent receiver URL.
descriptionstringEndpoint description.
eventsstring[]Current event subscriptions.
metadataobjectCustom metadata. The response may include fields maintained by the platform.
activebooleanWhether the Endpoint is enabled. New Endpoints are true.
signing_secretstringSecret used to verify Webhook signatures. Returned only in this response.
created_atstringCreation time, in RFC 3339 format.
Securely store signing_secret immediately. List, get, and update APIs do not return it again.

Errors

HTTPTypeTrigger
400invalid_request_errorThe URL, event list, metadata, or request body is invalid.
401authentication_errorAuthentication is missing, invalid, or expired.
403permission_errorThe current token cannot manage Webhooks.
409conflict_errorThe idempotency key conflicts with an existing request, or the Endpoint limit has been reached.
413invalid_request_errorThe request body is too large.
429rate_limit_errorThe request rate limit has been reached.