Skip to content
clearance.rest

Create an endpoint

POST
/webhooks/endpoints
curl --request POST \
  --url https://api.clearance.rest/webhooks/endpoints \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "url": "example", "event_types": [ "example" ], "description": "example", "enabled": true, "secret": "example" }'

A project can have at most 20 endpoints. The signing secret is returned only in this response and when it is rotated.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
url
required

Https URL (http is allowed only for localhost); at most 2048 characters.

string
event_types
required

Event types and patterns: an exact type, number.*, email_account.*, balance.* or *. At most 32 items.

Array<string>
description

At most 200 characters.

string | null
enabled

Defaults to true.

boolean
secret

Signing secret (16-128 characters). Generated when omitted.

string
>= 16 characters <= 128 characters
Examplegenerated
{
  "url": "example",
  "event_types": [
    "example"
  ],
  "description": "example",
  "enabled": true,
  "secret": "example"
}

Responses

Section titled “Responses”

201

Section titled “201”

Default Response

Media typeapplication/json
object
success
required
boolean
endpoint
required

A webhook subscription including its signing secret.

object
id
required
string
url
required
string
description
required
string | null
event_types
required

Subscribed event types and patterns.

Array<string>
enabled
required
boolean
disabled_reason
required

Why the endpoint is disabled: manual (disabled through the API) or failing (disabled automatically after repeated failed deliveries); null while enabled.

string | null
consecutive_failures
required
integer
>= -9007199254740991 <= 9007199254740991
last_success_at
required
Any of:

UTC timestamp (ISO 8601).

string
last_failure_at
required
Any of:

UTC timestamp (ISO 8601).

string
created_at
required

UTC timestamp (ISO 8601).

string
updated_at
required

UTC timestamp (ISO 8601).

string
secret
required

Signing secret (whsec_…). Returned only when the endpoint is created or its secret is rotated.

string
Example
{
  "success": true
}

400

Section titled “400”

Default Response

Media typeapplication/json

Error envelope returned by every JSON endpoint.

object
success
required
boolean
error
required
object
code
required

Machine-readable error code (snake_case).

string
message
required

Human-readable message.

string
details

Extra context for the error.

object
key
additional properties
Example
{
  "success": false
}

401

Section titled “401”

Default Response

Media typeapplication/json

Error envelope returned by every JSON endpoint.

object
success
required
boolean
error
required
object
code
required

Machine-readable error code (snake_case).

string
message
required

Human-readable message.

string
details

Extra context for the error.

object
key
additional properties
Example
{
  "success": false
}

403

Section titled “403”

Default Response

Media typeapplication/json

Error envelope returned by every JSON endpoint.

object
success
required
boolean
error
required
object
code
required

Machine-readable error code (snake_case).

string
message
required

Human-readable message.

string
details

Extra context for the error.

object
key
additional properties
Example
{
  "success": false
}

409

Section titled “409”

Default Response

Media typeapplication/json

Error envelope returned by every JSON endpoint.

object
success
required
boolean
error
required
object
code
required

Machine-readable error code (snake_case).

string
message
required

Human-readable message.

string
details

Extra context for the error.

object
key
additional properties
Example
{
  "success": false
}