Create a webhook endpoint

POST

/webhook-endpoints

curl --request POST \
  --url https://api.sendtruss.com/v1/webhook-endpoints \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "url": "example", "types": [ "example" ] }'

• Production

We send the webhook types you list to the URL, signed with your signing secrets. The URL must be public HTTPS on port 443. Your first endpoint also creates your first signing secret, which this response carries in signing_secret once and never again; it is null when you already have one.

Authorizations

• http

Request Body^required

Media typeapplication/json

object

url

required

A public HTTPS URL on port 443, up to 2,048 characters. A URL we refuse answers with a url_* code saying why.

string

types

required

The webhook types to send to it, at least one.

Array<string>

>= 1 items

Example^generated

{
  "url": "example",
  "types": [
    "example"
  ]
}

Responses

201

EndpointResource

Media typeapplication/json

object

data

required

EndpointResource

object

id

required

string

url

required

string

types

required

The webhook types we send to it.

Array

created_at

required

string | null

updated_at

required

string | null

signing_secret

required

object

id

required

string

secret

required

string

last_four

required

string

created_at

required

string | null

Example^generated

{
  "data": {
    "id": "example",
    "url": "example",
    "types": [
      "example"
    ],
    "created_at": "example",
    "updated_at": "example"
  },
  "signing_secret": {
    "id": "example",
    "secret": "example",
    "last_four": "example",
    "created_at": "example"
  }
}

Headers

Request-Id

required

string format: uuid

This request’s id. Quote it when you ask us about the request.

401

The API key is missing, malformed, revoked or expired.

Media typeapplication/json

object

message

required

What went wrong, for a person to read. It may change, so branch on code.

string

code

required

What went wrong, for your code to branch on. A new code is not a breaking change.

string

Allowed values: unauthenticated

doc_url

required

The entry on our errors page that explains this code.

string format: uri

request_id

required

This request’s id, the same as its Request-Id header. Quote it when you ask us about the request.

string format: uuid

Example

{
  "code": "unauthenticated"
}

Headers

Request-Id

required

string format: uuid

This request’s id. Quote it when you ask us about the request.

409

Refused because of the resource’s current state. The code says why.

Media typeapplication/json

object

message

required

What went wrong, for a person to read. It may change, so branch on code.

string

code

required

What went wrong, for your code to branch on. A new code is not a breaking change.

string

Allowed values: endpoint_ceiling_reached

doc_url

required

The entry on our errors page that explains this code.

string format: uri

request_id

required

This request’s id, the same as its Request-Id header. Quote it when you ask us about the request.

string format: uuid

Example

{
  "code": "endpoint_ceiling_reached"
}

Headers

Request-Id

required

string format: uuid

This request’s id. Quote it when you ask us about the request.

422

The request is invalid. The code says why, and errors names each field at fault.

Media typeapplication/json

Any of:

object

object

message

required

What went wrong, for a person to read. It may change, so branch on code.

string

code

required

What went wrong, for your code to branch on. A new code is not a breaking change.

string

Allowed values: validation_failed

errors

required

Each field that failed validation, by its path in the request, with its messages.

object

key

additional properties

Array<string>

doc_url

required

The entry on our errors page that explains this code.

string format: uri

request_id

required

This request’s id, the same as its Request-Id header. Quote it when you ask us about the request.

string format: uuid

object

object

message

required

What went wrong, for a person to read. It may change, so branch on code.

string

code

required

What went wrong, for your code to branch on. A new code is not a breaking change.

string

Allowed values: url_invalid url_too_long url_not_https url_port_not_allowed url_ip_literal url_has_credentials url_has_email_address url_unresolvable url_address_refused unknown_type

doc_url

required

The entry on our errors page that explains this code.

string format: uri

request_id

required

This request’s id, the same as its Request-Id header. Quote it when you ask us about the request.

string format: uuid

Example

{
  "code": "validation_failed"
}

Headers

Request-Id

required

string format: uuid

This request’s id. Quote it when you ask us about the request.

429

Too many requests. Wait for the seconds in Retry-After.

Media typeapplication/json

object

message

required

What went wrong, for a person to read. It may change, so branch on code.

string

code

required

What went wrong, for your code to branch on. A new code is not a breaking change.

string

Allowed values: rate_limited

doc_url

required

The entry on our errors page that explains this code.

string format: uri

request_id

required

This request’s id, the same as its Request-Id header. Quote it when you ask us about the request.

string format: uuid

Example

{
  "code": "rate_limited"
}

Headers

Request-Id

required

string format: uuid

This request’s id. Quote it when you ask us about the request.

Retry-After

integer

Seconds to wait before trying again.