Chevre REST API Endpoints — Webhooks and Event Delivery

Webhooks let you subscribe to events that happen in Chevre and receive real-time HTTP POST notifications to a URL you control. When an event fires, Chevre sends a signed JSON payload to each registered webhook URL that subscribes to that event. Use the endpoints below to register, update, and remove webhooks. All management requests require your API key in the Authorization header as Bearer <your_api_key>.

List webhooks

GET https://api.chevre.io/v1/webhooks Returns all webhooks registered for the authenticated workspace.

Example request

curl --request GET \
  --url "https://api.chevre.io/v1/webhooks" \
  --header "Authorization: Bearer <your_api_key>" \
  --header "Accept: application/json"

import requests

response = requests.get(
    "https://api.chevre.io/v1/webhooks",
    headers={"Authorization": "Bearer <your_api_key>"},
)
print(response.json())

const response = await fetch("https://api.chevre.io/v1/webhooks", {
  headers: {
    Authorization: "Bearer <your_api_key>",
    Accept: "application/json",
  },
});
const data = await response.json();
console.log(data);

Example response

200

{
  "data": [
    {
      "id": "wh_01RST",
      "url": "https://example.com/chevre-webhook",
      "events": [
        "automation.run.completed",
        "automation.run.failed",
        "member.invited"
      ],
      "enabled": true,
      "created_at": "2024-04-10T08:00:00Z",
      "updated_at": "2024-05-15T12:00:00Z"
    }
  ]
}

Response fields

data

array

An array of webhook objects registered to the workspace.

Show webhook object

string

The unique identifier for the webhook, prefixed with wh_.

url

string

The destination URL that Chevre POSTs event payloads to.

events

array

The list of event types this webhook is subscribed to.

enabled

boolean

Whether the webhook is currently active. Disabled webhooks do not receive event deliveries.

created_at

string

ISO 8601 timestamp of when the webhook was registered.

updated_at

string

ISO 8601 timestamp of the most recent update.

Create a webhook

POST https://api.chevre.io/v1/webhooks Registers a new webhook endpoint. Chevre immediately sends a test ping to the URL to verify reachability — the endpoint must respond with a 2xx status code within 5 seconds or the registration will fail.

Request body

url

string

required

The HTTPS URL that Chevre will send event payloads to. Must use https://. Plain HTTP URLs are rejected.

events

array

required

An array of event type strings the webhook should subscribe to. At least one event is required. See Available events for the full list.

secret

string

required

A signing secret used to compute the Chevre-Signature HMAC-SHA256 header on each delivery. Store this value securely — you cannot retrieve it after creation.

enabled

boolean

default:"true"

Whether the webhook should be active immediately after creation.

Example request

curl --request POST \
  --url "https://api.chevre.io/v1/webhooks" \
  --header "Authorization: Bearer <your_api_key>" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/chevre-webhook",
    "events": [
      "automation.run.completed",
      "automation.run.failed",
      "member.invited"
    ],
    "secret": "your-signing-secret",
    "enabled": true
  }'

import requests

response = requests.post(
    "https://api.chevre.io/v1/webhooks",
    json={
        "url": "https://example.com/chevre-webhook",
        "events": [
            "automation.run.completed",
            "automation.run.failed",
            "member.invited",
        ],
        "secret": "your-signing-secret",
        "enabled": True,
    },
    headers={"Authorization": "Bearer <your_api_key>"},
)
print(response.json())

const response = await fetch("https://api.chevre.io/v1/webhooks", {
  method: "POST",
  headers: {
    Authorization: "Bearer <your_api_key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/chevre-webhook",
    events: [
      "automation.run.completed",
      "automation.run.failed",
      "member.invited",
    ],
    secret: "your-signing-secret",
    enabled: true,
  }),
});
const data = await response.json();
console.log(data);

Example response

201

{
  "data": {
    "id": "wh_01RST",
    "url": "https://example.com/chevre-webhook",
    "events": [
      "automation.run.completed",
      "automation.run.failed",
      "member.invited"
    ],
    "enabled": true,
    "created_at": "2024-06-01T14:22:00Z",
    "updated_at": "2024-06-01T14:22:00Z"
  }
}

The secret field is write-only and is not returned in any response after creation. Store it securely at registration time.

Response fields

data

object

The newly registered webhook object.

Show webhook object

string

The unique identifier for the webhook, prefixed with wh_.

url

string

The destination URL for event delivery.

events

array

The list of event types this webhook is subscribed to.

enabled

boolean

Whether the webhook is currently active.

created_at

string

ISO 8601 timestamp of when the webhook was registered.

updated_at

string

ISO 8601 timestamp of the most recent update.

Get a webhook

GET https://api.chevre.io/v1/webhooks/{id} Retrieves a single webhook by its ID.

Path parameters

string

required

The unique identifier of the webhook to retrieve (e.g. wh_01RST).

Example request

curl --request GET \
  --url "https://api.chevre.io/v1/webhooks/wh_01RST" \
  --header "Authorization: Bearer <your_api_key>" \
  --header "Accept: application/json"

import requests

response = requests.get(
    "https://api.chevre.io/v1/webhooks/wh_01RST",
    headers={"Authorization": "Bearer <your_api_key>"},
)
print(response.json())

const response = await fetch("https://api.chevre.io/v1/webhooks/wh_01RST", {
  headers: {
    Authorization: "Bearer <your_api_key>",
    Accept: "application/json",
  },
});
const data = await response.json();
console.log(data);

Example response

200

{
  "data": {
    "id": "wh_01RST",
    "url": "https://example.com/chevre-webhook",
    "events": [
      "automation.run.completed",
      "automation.run.failed",
      "member.invited"
    ],
    "enabled": true,
    "created_at": "2024-04-10T08:00:00Z",
    "updated_at": "2024-05-15T12:00:00Z"
  }
}

Response fields

data

object

The requested webhook object.

Show webhook object

string

The unique identifier for the webhook.

url

string

The destination URL for event delivery.

events

array

The list of event types this webhook is subscribed to.

enabled

boolean

Whether the webhook is currently active.

created_at

string

ISO 8601 timestamp of when the webhook was registered.

updated_at

string

ISO 8601 timestamp of the most recent update.

Update a webhook

PATCH https://api.chevre.io/v1/webhooks/{id} Updates an existing webhook’s URL, event subscriptions, or enabled state. Send only the fields you want to change.

Path parameters

string

required

The unique identifier of the webhook to update (e.g. wh_01RST).

Request body

url

string

A new destination URL. Must use https://. Chevre will send a test ping to the new URL to verify reachability.

events

array

A replacement list of event type strings. The entire events array is replaced — to add a single event, include all existing events plus the new one.

enabled

boolean

Set to false to pause event delivery, or true to resume it.

Example request

curl --request PATCH \
  --url "https://api.chevre.io/v1/webhooks/wh_01RST" \
  --header "Authorization: Bearer <your_api_key>" \
  --header "Content-Type: application/json" \
  --data '{
    "events": [
      "automation.run.completed",
      "automation.run.failed",
      "member.invited",
      "project.created"
    ],
    "enabled": true
  }'

import requests

response = requests.patch(
    "https://api.chevre.io/v1/webhooks/wh_01RST",
    json={
        "events": [
            "automation.run.completed",
            "automation.run.failed",
            "member.invited",
            "project.created",
        ],
        "enabled": True,
    },
    headers={"Authorization": "Bearer <your_api_key>"},
)
print(response.json())

const response = await fetch("https://api.chevre.io/v1/webhooks/wh_01RST", {
  method: "PATCH",
  headers: {
    Authorization: "Bearer <your_api_key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    events: [
      "automation.run.completed",
      "automation.run.failed",
      "member.invited",
      "project.created",
    ],
    enabled: true,
  }),
});
const data = await response.json();
console.log(data);

Example response

200

{
  "data": {
    "id": "wh_01RST",
    "url": "https://example.com/chevre-webhook",
    "events": [
      "automation.run.completed",
      "automation.run.failed",
      "member.invited",
      "project.created"
    ],
    "enabled": true,
    "created_at": "2024-04-10T08:00:00Z",
    "updated_at": "2024-06-10T11:30:00Z"
  }
}

Response fields

data

object

The updated webhook object.

Show webhook object

string

The unique identifier for the webhook.

url

string

The updated or unchanged destination URL.

events

array

The updated list of subscribed event types.

enabled

boolean

The updated enabled state.

created_at

string

ISO 8601 timestamp of when the webhook was originally registered.

updated_at

string

ISO 8601 timestamp of this update.

Delete a webhook

DELETE https://api.chevre.io/v1/webhooks/{id} Permanently deletes a webhook registration. Chevre immediately stops sending event deliveries to this endpoint.

Path parameters

string

required

The unique identifier of the webhook to delete (e.g. wh_01RST).

Example request

curl --request DELETE \
  --url "https://api.chevre.io/v1/webhooks/wh_01RST" \
  --header "Authorization: Bearer <your_api_key>"

import requests

response = requests.delete(
    "https://api.chevre.io/v1/webhooks/wh_01RST",
    headers={"Authorization": "Bearer <your_api_key>"},
)
print(response.status_code)  # 204

const response = await fetch("https://api.chevre.io/v1/webhooks/wh_01RST", {
  method: "DELETE",
  headers: {
    Authorization: "Bearer <your_api_key>",
  },
});
console.log(response.status); // 204

Example response

204

// No content returned on successful deletion

A successful deletion returns HTTP 204 No Content with an empty response body.

Available webhook events

Subscribe to any combination of the following events when creating or updating a webhook.

Automation
Member
Project

Event	Description
`automation.run.started`	An automation run has begun executing.
`automation.run.completed`	An automation run finished successfully.
`automation.run.failed`	An automation run encountered an error and stopped.
`automation.created`	A new automation was created in a project.
`automation.updated`	An automation’s configuration was changed.
`automation.deleted`	An automation was deleted from a project.

Event	Description
`member.invited`	A new invitation was sent to a user.
`member.joined`	An invited user accepted their invitation.
`member.role_changed`	A member’s role was updated.
`member.removed`	A member was removed from the workspace.

Event	Description
`project.created`	A new project was created in the workspace.
`project.updated`	A project’s details were changed.
`project.archived`	A project was archived.
`project.deleted`	A project was permanently deleted.

Webhook payload format

Chevre delivers all events as HTTP POST requests with a JSON body. Every payload follows the same top-level envelope structure, with resource-specific data nested inside the data field.

{
  "id": "evt_01XYZ",
  "type": "automation.run.completed",
  "created_at": "2024-06-01T14:22:00Z",
  "data": {
    "automation_id": "auto_01GHI",
    "run_id": "run_01DEF",
    "status": "success"
  }
}

string

A unique identifier for this event delivery, prefixed with evt_. Use this to deduplicate retried deliveries.

type

string

The event type string that triggered this delivery (e.g. "automation.run.completed").

created_at

string

ISO 8601 timestamp of when the event occurred in Chevre.

data

object

The event-specific payload. The fields inside data vary depending on the type. Refer to the Available events section for per-event data shapes.

Signature verification

Every webhook delivery from Chevre includes a Chevre-Signature header containing an HMAC-SHA256 signature computed over the raw request body using the secret you provided at registration. Always verify this signature before processing a payload.

const crypto = require("crypto");

function verifyChevreSignature(rawBody, signatureHeader, secret) {
  // Compute expected signature
  const expectedSignature = crypto
    .createHmac("sha256", secret)
    .update(rawBody, "utf8")
    .digest("hex");

  // Compare using a timing-safe comparison to prevent timing attacks
  const trusted = Buffer.from(`sha256=${expectedSignature}`, "utf8");
  const received = Buffer.from(signatureHeader, "utf8");

  if (trusted.length !== received.length) {
    return false;
  }

  return crypto.timingSafeEqual(trusted, received);
}

// Express.js example
app.post("/chevre-webhook", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.headers["chevre-signature"];
  const isValid = verifyChevreSignature(req.body, signature, process.env.CHEVRE_WEBHOOK_SECRET);

  if (!isValid) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(req.body);
  console.log("Received event:", event.type);

  // Acknowledge receipt immediately
  res.status(200).send("OK");
});

import hashlib
import hmac
import os

def verify_chevre_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
    """Verify the HMAC-SHA256 signature on a Chevre webhook delivery."""
    expected_signature = hmac.new(
        secret.encode("utf-8"),
        raw_body,
        hashlib.sha256,
    ).hexdigest()

    expected = f"sha256={expected_signature}"

    # Use hmac.compare_digest to prevent timing attacks
    return hmac.compare_digest(expected, signature_header)


# Flask example
from flask import Flask, request, abort
import json

app = Flask(__name__)

@app.route("/chevre-webhook", methods=["POST"])
def chevre_webhook():
    raw_body = request.get_data()
    signature = request.headers.get("Chevre-Signature", "")
    secret = os.environ["CHEVRE_WEBHOOK_SECRET"]

    if not verify_chevre_signature(raw_body, signature, secret):
        abort(401)

    event = json.loads(raw_body)
    print(f"Received event: {event['type']}")

    # Acknowledge receipt immediately
    return "OK", 200

Always use a timing-safe comparison function (such as crypto.timingSafeEqual in Node.js or hmac.compare_digest in Python) when comparing signatures. A standard equality check is vulnerable to timing attacks.

Retry behavior

If your endpoint does not respond with a 2xx HTTP status code within 10 seconds, Chevre marks the delivery as failed and retries it automatically. Chevre retries failed deliveries up to 5 times using exponential backoff with jitter:

Attempt	Delay
1st retry	~30 seconds
2nd retry	~5 minutes
3rd retry	~30 minutes
4th retry	~2 hours
5th retry	~8 hours

After all 5 retries are exhausted, the delivery is marked as permanently failed. You can view delivery attempts and their statuses in the Chevre dashboard under Settings → Webhooks.

Respond to webhook deliveries as quickly as possible with a 200 OK — ideally before doing any processing. Offload heavy work to a background queue after acknowledging receipt. This prevents Chevre from timing out and triggering unnecessary retries.

You can use the event id field to safely deduplicate retried deliveries in case your handler processes the same event more than once.

​List webhooks

​Example request

​Example response

​Response fields

​Create a webhook

​Request body

​Example request

​Example response

​Response fields

​Get a webhook

​Path parameters

​Example request

​Example response

​Response fields

​Update a webhook

​Path parameters

​Request body

​Example request

​Example response

​Response fields

​Delete a webhook

​Path parameters

​Example request

​Example response

​Available webhook events

​Webhook payload format

​Signature verification

​Retry behavior

List webhooks

Example request

Example response

Response fields

Create a webhook

Request body

Example request

Example response

Response fields

Get a webhook

Path parameters

Example request

Example response

Response fields

Update a webhook

Path parameters

Request body

Example request

Example response

Response fields

Delete a webhook

Path parameters

Example request

Example response

Available webhook events

Webhook payload format

Signature verification

Retry behavior