Create webhook endpoint

Creates a webhook endpoint and returns its whsec_… signing secret. Deliveries follow the Standard Webhooks spec (webhook-id, webhook-timestamp, webhook-signature). At most 20 endpoints per organization (422 unprocessable beyond).

POST

/v1/webhooks

Authorization

bearerAuth

headerAuthorizationBearer <token>

An organization API key (koast_sk_…) with the API surface enabled, or an OAuth access token issued by Koast (koast_at_…) whose audience covers this API. REST access requires an active Agency plan.

Header Parameters

Request Body

application/json

body

url*string

HTTPS URL Koast POSTs events to. No credentials in the URL; redirects are not followed.

Length1 <= length <= 2048

eventTypes*array<>

Event types this endpoint receives. ping is always delivered by the test send and cannot be subscribed to.

Items1 <= items

brandIds?array<>|

Only deliver events of these brands. Null delivers events of every brand in the organization.

Response Body

Create webhook endpoint

application/json

response

id*string

url*string

eventTypes*array<string>

brandIds*array<number>|null

status*string

disabled_by_failures means Koast gave up after ~3 days of failed deliveries; enable it again once fixed.

Value in"enabled""disabled""disabled_by_failures"

disabledReason*string|null

disabledAt*string|null

consecutiveFailures*integer

Range-9007199254740991 <= value <= 9007199254740991

lastSuccessAt*string|null

lastFailureAt*string|null

lastError*string|null

secretRotationExpiresAt*|

While set, deliveries are signed with both the new and the previous secret.

createdAt*string

updatedAt*string

secret*string

The whsec_… signing secret. Verify deliveries with any Standard Webhooks library.

curl -X POST "https://example.com/v1/webhooks" \  -H "Authorization: Bearer koast_sk_..." \  -H "Content-Type: application/json" \  -d '{    "url": "string",    "eventTypes": [      "launch.completed"    ]  }'

{  "id": "string",  "url": "string",  "eventTypes": [    "string"  ],  "brandIds": [    0  ],  "status": "enabled",  "disabledReason": "string",  "disabledAt": "string",  "consecutiveFailures": -9007199254740991,  "lastSuccessAt": "string",  "lastFailureAt": "string",  "lastError": "string",  "secretRotationExpiresAt": "string",  "createdAt": "string",  "updatedAt": "string",  "secret": "string"}

Required scope: write. CLI: koast create-webhook-endpoint, see Webhooks commands. Authentication, headers, errors and pagination work the same on every operation. See Conventions.