Webhooks

9 endpoints: list webhook endpoints, create a webhook endpoint, retrieve a webhook endpoint, update a webhook endpoint, delete a webhook endpoint, roll a webhook secret, send a test event, list deliveries, retry a delivery.

List webhook endpoints: GET /v1/webhook_endpoints
Create a webhook endpoint: POST /v1/webhook_endpoints
Retrieve a webhook endpoint: GET /v1/webhook_endpoints/{endpoint_id}
Update a webhook endpoint: PATCH /v1/webhook_endpoints/{endpoint_id}
Delete a webhook endpoint: DELETE /v1/webhook_endpoints/{endpoint_id}
Roll a webhook secret: POST /v1/webhook_endpoints/{endpoint_id}/roll_secret
Send a test event: POST /v1/webhook_endpoints/{endpoint_id}/test
List deliveries: GET /v1/webhook_endpoints/{endpoint_id}/deliveries
Retry a delivery: POST /v1/webhook_deliveries/{delivery_id}/retry

List webhook endpoints

GET /v1/webhook_endpoints

Lists the Workspace's webhook endpoints. Secrets are never listed.

Permission: webhooks:read

Response

Field	Type	Required	Description
`object`	`"list"`	Yes
`data`	array of object	Yes
`data[].object`	`"webhook_endpoint"`	Yes
`data[].id`	string	Yes	(up to 128 characters)
`data[].url`	string	Yes
`data[].description`	string or null	Yes
`data[].enabled_events`	array of string	Yes
`data[].project_ids`	array of string	Yes
`data[].api_version`	string	Yes
`data[].include_comment_content`	boolean	Yes
`data[].status`	`enabled`, `disabled`	Yes
`data[].disabled_reason`	string or null	Yes	manual, gone (the endpoint answered 410) or failing (five days of failures).
`data[].failing_since`	string or null	Yes
`data[].secret_last4`	string or null	Yes
`data[].created_at`	string	Yes	ISO 8601 date and time, UTC.
`has_more`	boolean	Yes
`next_cursor`	string or null	Yes

curl https://api.nowscale.com/v1/webhook_endpoints \
  -H "Authorization: Bearer $NOWSCALE_API_KEY"

Create a webhook endpoint

POST /v1/webhook_endpoints

Adds an https endpoint (port 443) that receives the events you choose, signed with its own whsec_ secret. The secret is in this response only; reveal it later in Settings.

Permission: webhooks:write · Accepts Idempotency-Key · Answers 201

Body

Field	Type	Required	Description
`url`	string	Yes	(up to 2048 characters)
`description`	string	No	(up to 200 characters)
`enabled_events`	array of `*`, `post.created`, `post.published`, `post.partially_published`, `post.failed`, `post.deleted`	Yes	Event types to receive, or ["*"] for all.
`project_ids`	array of string	No	Only events from these Projects. Empty or absent: every Project.
`include_comment_content`	boolean	No	Comment events carry the comment's text and author name.

Response

Field	Type	Required	Description
`object`	`"webhook_endpoint"`	Yes
`id`	string	Yes	(up to 128 characters)
`url`	string	Yes
`description`	string or null	Yes
`enabled_events`	array of string	Yes
`project_ids`	array of string	Yes
`api_version`	string	Yes
`include_comment_content`	boolean	Yes
`status`	`enabled`, `disabled`	Yes
`disabled_reason`	string or null	Yes	manual, gone (the endpoint answered 410) or failing (five days of failures).
`failing_since`	string or null	Yes
`secret_last4`	string or null	Yes
`created_at`	string	Yes	ISO 8601 date and time, UTC.
`secret`	string	Yes	The signing secret, shown once.

curl -X POST https://api.nowscale.com/v1/webhook_endpoints \
  -H "Authorization: Bearer $NOWSCALE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ ... }'

Retrieve a webhook endpoint

GET /v1/webhook_endpoints/{endpoint_id}

Returns one endpoint, with the last four characters of its secret.

Permission: webhooks:read

Path parameters

Name	Description
`endpoint_id`	The endpoint's id.

Response

Field	Type	Required	Description
`object`	`"webhook_endpoint"`	Yes
`id`	string	Yes	(up to 128 characters)
`url`	string	Yes
`description`	string or null	Yes
`enabled_events`	array of string	Yes
`project_ids`	array of string	Yes
`api_version`	string	Yes
`include_comment_content`	boolean	Yes
`status`	`enabled`, `disabled`	Yes
`disabled_reason`	string or null	Yes	manual, gone (the endpoint answered 410) or failing (five days of failures).
`failing_since`	string or null	Yes
`secret_last4`	string or null	Yes
`created_at`	string	Yes	ISO 8601 date and time, UTC.

curl https://api.nowscale.com/v1/webhook_endpoints/ENDPOINT_ID \
  -H "Authorization: Bearer $NOWSCALE_API_KEY"

Update a webhook endpoint

PATCH /v1/webhook_endpoints/{endpoint_id}

Changes the URL, events, Projects or description, or turns the endpoint off and on. Turning it on clears a failing streak.

Permission: webhooks:write

Path parameters

Name	Description
`endpoint_id`	The endpoint's id.

Body

Field	Type	Required	Description
`url`	string	No	(up to 2048 characters)
`description`	string or null	No
`enabled_events`	array of `*`, `post.created`, `post.published`, `post.partially_published`, `post.failed`, `post.deleted`	No	Event types to receive, or ["*"] for all.
`project_ids`	array of string	No
`include_comment_content`	boolean	No
`enabled`	boolean	No

Response

Field	Type	Required	Description
`object`	`"webhook_endpoint"`	Yes
`id`	string	Yes	(up to 128 characters)
`url`	string	Yes
`description`	string or null	Yes
`enabled_events`	array of string	Yes
`project_ids`	array of string	Yes
`api_version`	string	Yes
`include_comment_content`	boolean	Yes
`status`	`enabled`, `disabled`	Yes
`disabled_reason`	string or null	Yes	manual, gone (the endpoint answered 410) or failing (five days of failures).
`failing_since`	string or null	Yes
`secret_last4`	string or null	Yes
`created_at`	string	Yes	ISO 8601 date and time, UTC.

curl -X PATCH https://api.nowscale.com/v1/webhook_endpoints/ENDPOINT_ID \
  -H "Authorization: Bearer $NOWSCALE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Delete a webhook endpoint

DELETE /v1/webhook_endpoints/{endpoint_id}

Deletes the endpoint and the deliveries still waiting for it.

Permission: webhooks:write

Path parameters

Name	Description
`endpoint_id`	The endpoint's id.

Response

Field	Type	Required	Description
`object`	`"webhook_endpoint"`	Yes
`id`	string	Yes	(up to 128 characters)
`deleted`	`true`	Yes

curl -X DELETE https://api.nowscale.com/v1/webhook_endpoints/ENDPOINT_ID \
  -H "Authorization: Bearer $NOWSCALE_API_KEY"

Roll a webhook secret

POST /v1/webhook_endpoints/{endpoint_id}/roll_secret

Creates a new signing secret. The old one keeps signing alongside it for 24 hours (two signatures per delivery) unless expire_now is true.

Permission: webhooks:write · Accepts Idempotency-Key

Path parameters

Name	Description
`endpoint_id`	The endpoint's id.

Body

Field	Type	Required	Description
`expire_now`	boolean	No

Response

Field	Type	Required	Description
`object`	`"webhook_endpoint"`	Yes
`id`	string	Yes	(up to 128 characters)
`url`	string	Yes
`description`	string or null	Yes
`enabled_events`	array of string	Yes
`project_ids`	array of string	Yes
`api_version`	string	Yes
`include_comment_content`	boolean	Yes
`status`	`enabled`, `disabled`	Yes
`disabled_reason`	string or null	Yes	manual, gone (the endpoint answered 410) or failing (five days of failures).
`failing_since`	string or null	Yes
`secret_last4`	string or null	Yes
`created_at`	string	Yes	ISO 8601 date and time, UTC.
`secret`	string	Yes

curl -X POST https://api.nowscale.com/v1/webhook_endpoints/ENDPOINT_ID/roll_secret \
  -H "Authorization: Bearer $NOWSCALE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ ... }'

Send a test event

POST /v1/webhook_endpoints/{endpoint_id}/test

Queues a webhook_endpoint.test event to this endpoint, whatever its event filter.

Permission: webhooks:write · Answers 202

Path parameters

Name	Description
`endpoint_id`	The endpoint's id.

Response

Field	Type	Required	Description
`object`	`"webhook_delivery"`	Yes
`id`	string	Yes	(up to 128 characters)
`event_id`	string	Yes	(up to 128 characters)
`status`	`"pending"`	Yes

curl -X POST https://api.nowscale.com/v1/webhook_endpoints/ENDPOINT_ID/test \
  -H "Authorization: Bearer $NOWSCALE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

List deliveries

GET /v1/webhook_endpoints/{endpoint_id}/deliveries

Lists an endpoint's deliveries of the last 30 days, newest first, with their attempts' outcome.

Permission: webhooks:read

Path parameters

Name	Description
`endpoint_id`	The endpoint's id.

Query parameters

Field	Type	Required	Description
`limit`	integer	No	Items per page, 1 to 100. (1 to 100, default 25)
`cursor`	string	No	The next_cursor of the previous page. (up to 512 characters)
`status`	`pending`, `delivering`, `succeeded`, `failed`	No

Response

Field	Type	Required	Description
`object`	`"list"`	Yes
`data`	array of object	Yes
`data[].object`	`"webhook_delivery"`	Yes
`data[].id`	string	Yes	(up to 128 characters)
`data[].endpoint_id`	string	Yes	(up to 128 characters)
`data[].event_id`	string	Yes	(up to 128 characters)
`data[].event_type`	string	Yes
`data[].status`	`pending`, `delivering`, `succeeded`, `failed`	Yes
`data[].attempts`	integer	Yes	(-9007199254740991 to 9007199254740991)
`data[].next_attempt_at`	string or null	Yes
`data[].last_status_code`	integer or null	Yes
`data[].last_error`	string or null	Yes
`data[].delivered_at`	string or null	Yes
`data[].created_at`	string	Yes	ISO 8601 date and time, UTC.
`has_more`	boolean	Yes
`next_cursor`	string or null	Yes

curl https://api.nowscale.com/v1/webhook_endpoints/ENDPOINT_ID/deliveries \
  -H "Authorization: Bearer $NOWSCALE_API_KEY"

Retry a delivery

POST /v1/webhook_deliveries/{delivery_id}/retry

Sends a delivery again now, keeping its webhook-id, whatever its status.

Permission: webhooks:write · Answers 202

Path parameters

Name	Description
`delivery_id`	The delivery's id.

Response

Field	Type	Required	Description
`object`	`"webhook_delivery"`	Yes
`id`	string	Yes	(up to 128 characters)
`endpoint_id`	string	Yes	(up to 128 characters)
`event_id`	string	Yes	(up to 128 characters)
`event_type`	string	Yes
`status`	`pending`, `delivering`, `succeeded`, `failed`	Yes
`attempts`	integer	Yes	(-9007199254740991 to 9007199254740991)
`next_attempt_at`	string or null	Yes
`last_status_code`	integer or null	Yes
`last_error`	string or null	Yes
`delivered_at`	string or null	Yes
`created_at`	string	Yes	ISO 8601 date and time, UTC.

curl -X POST https://api.nowscale.com/v1/webhook_deliveries/DELIVERY_ID/retry \
  -H "Authorization: Bearer $NOWSCALE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'