Create a webhook endpoint

curl --request POST \
  --url https://api2.endstate.io/v1/webhooks/endpoints \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://hooks.example.com/endstate",
  "event_types": [
    "example.updated"
  ],
  "description": "Production listener"
}
'

import requests

url = "https://api2.endstate.io/v1/webhooks/endpoints"

payload = {
    "url": "https://hooks.example.com/endstate",
    "event_types": ["example.updated"],
    "description": "Production listener"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    url: 'https://hooks.example.com/endstate',
    event_types: ['example.updated'],
    description: 'Production listener'
  })
};

fetch('https://api2.endstate.io/v1/webhooks/endpoints', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api2.endstate.io/v1/webhooks/endpoints",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'url' => 'https://hooks.example.com/endstate',
    'event_types' => [
        'example.updated'
    ],
    'description' => 'Production listener'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api2.endstate.io/v1/webhooks/endpoints"

	payload := strings.NewReader("{\n  \"url\": \"https://hooks.example.com/endstate\",\n  \"event_types\": [\n    \"example.updated\"\n  ],\n  \"description\": \"Production listener\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api2.endstate.io/v1/webhooks/endpoints")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"url\": \"https://hooks.example.com/endstate\",\n  \"event_types\": [\n    \"example.updated\"\n  ],\n  \"description\": \"Production listener\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api2.endstate.io/v1/webhooks/endpoints")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"url\": \"https://hooks.example.com/endstate\",\n  \"event_types\": [\n    \"example.updated\"\n  ],\n  \"description\": \"Production listener\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "8e1a7f50-90ab-4cde-8012-3456789abcde",
  "url": "https://hooks.example.com/endstate",
  "event_types": [
    "example.updated"
  ],
  "description": "Production listener",
  "status": "enabled",
  "disabled_reason": null,
  "fail_since": null,
  "api_version": "2026-09-01",
  "created_at": "2026-09-22T12:00:00.000Z",
  "updated_at": "2026-09-22T12:00:00.000Z",
  "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
}

POST

webhooks

endpoints

Create a webhook endpoint

curl --request POST \
  --url https://api2.endstate.io/v1/webhooks/endpoints \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://hooks.example.com/endstate",
  "event_types": [
    "example.updated"
  ],
  "description": "Production listener"
}
'

import requests

url = "https://api2.endstate.io/v1/webhooks/endpoints"

payload = {
    "url": "https://hooks.example.com/endstate",
    "event_types": ["example.updated"],
    "description": "Production listener"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    url: 'https://hooks.example.com/endstate',
    event_types: ['example.updated'],
    description: 'Production listener'
  })
};

fetch('https://api2.endstate.io/v1/webhooks/endpoints', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api2.endstate.io/v1/webhooks/endpoints",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'url' => 'https://hooks.example.com/endstate',
    'event_types' => [
        'example.updated'
    ],
    'description' => 'Production listener'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api2.endstate.io/v1/webhooks/endpoints"

	payload := strings.NewReader("{\n  \"url\": \"https://hooks.example.com/endstate\",\n  \"event_types\": [\n    \"example.updated\"\n  ],\n  \"description\": \"Production listener\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api2.endstate.io/v1/webhooks/endpoints")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"url\": \"https://hooks.example.com/endstate\",\n  \"event_types\": [\n    \"example.updated\"\n  ],\n  \"description\": \"Production listener\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api2.endstate.io/v1/webhooks/endpoints")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"url\": \"https://hooks.example.com/endstate\",\n  \"event_types\": [\n    \"example.updated\"\n  ],\n  \"description\": \"Production listener\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "8e1a7f50-90ab-4cde-8012-3456789abcde",
  "url": "https://hooks.example.com/endstate",
  "event_types": [
    "example.updated"
  ],
  "description": "Production listener",
  "status": "enabled",
  "disabled_reason": null,
  "fail_since": null,
  "api_version": "2026-09-01",
  "created_at": "2026-09-22T12:00:00.000Z",
  "updated_at": "2026-09-22T12:00:00.000Z",
  "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
}

Authorizations

Authorization

string

header

required

Use Authorization: Bearer end_sk_* for partner API keys (e.g. end_sk_AbCd_example_api_key).

Headers

Idempotency-Key

string

Unique key that makes this request safe to retry. Replaying the key with the same body returns the original response with Idempotent-Replayed: true; replaying it with a different body returns 409 idempotency.key_conflict.

Required string length: 1 - 255

Example:

"a1b2c3d4-0000-4000-8000-000000000000"

Body

application/json

url

string<uri>

required

HTTPS URL on a public host.

Maximum string length: 2048

Example:

"https://hooks.example.com/endstate"

event_types

string[]

required

Required array length: 1 - 64 elements

Minimum string length: 1

Example:

["example.updated"]

description

string

Maximum string length: 512

api_version

string

Dated payload version; must be the current version or an older one the platform still renders.

Pattern: ^\d{4}-\d{2}-\d{2}$

Example:

"2026-09-01"

Response

The created endpoint with its signing secret.

string<uuid>

required

Example:

"8e1a7f50-90ab-4cde-8012-3456789abcde"

url

string<uri>

required

HTTPS URL that receives deliveries.

Example:

"https://hooks.example.com/endstate"

event_types

string[]

required

Event types this endpoint is subscribed to.

Example:

["example.updated"]

description

string | null

required

status

enum<string>

required

disabled on the first failed delivery after fail_since is five days old, after a 410 response, or when deleted. Re-enable with PATCH.

Available options:

enabled,

disabled

Example:

"enabled"

disabled_reason

string | null

required

fail_since

string<date-time> | null

required

When the current run of failed deliveries began, or null while deliveries succeed. The next failed delivery after this is five days old disables the endpoint, so fix the receiver before then.

Example:

null

api_version

string

required

Dated payload version this endpoint receives.

Example:

"2026-09-01"

created_at

string<date-time>

required

updated_at

string<date-time>

required

secret

string

Signing secret for this endpoint. Present on the first response only: an idempotent replay of the same request (Idempotent-Replayed: true) omits it. An admin API key can read it again through the secret endpoint; every read is recorded.

Example:

"whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"

Overview

Endpoints

Create a webhook endpoint

Authorizations

Headers

Body

Response