Webhooks

Use the webhooks API to programmatically manage your event endpoints. You can register multiple endpoints with different event subscriptions — for example, one endpoint for ATS sync and another for Slack notifications.

List Webhooks

Retrieve all webhook endpoints registered for your organization.

GET https://api.cutshort.io/v1/webhooks

cURL

curl 'https://api.cutshort.io/v1/webhooks' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response

{
  "data": [
    {
      "id": "wh_6kMpL3nR",
      "url": "https://yourapp.com/cutshort-events",
      "events": ["candidate.shortlisted", "invite.accepted"],
      "status": "active",
      "created_at": "2024-01-15T10:00:00Z"
    },
    {
      "id": "wh_9pNqR5sT",
      "url": "https://yourapp.com/slack-relay",
      "events": ["candidate.stage_changed", "offer.made"],
      "status": "active",
      "created_at": "2024-01-18T08:30:00Z"
    }
  ]
}

Register a Webhook

Subscribe a new HTTPS endpoint to one or more event types.

POST https://api.cutshort.io/v1/webhooks

Request Body

string

required

The HTTPS URL that will receive webhook events. The endpoint must be publicly accessible and respond to POST requests.

array of strings

required

List of event types to subscribe to. See the Webhook Events Reference for all valid values.

string

A custom signing secret used for HMAC-SHA256 signature verification. If omitted, Cutshort generates a secret automatically and returns it in the response.

Example Request

curl -X POST 'https://api.cutshort.io/v1/webhooks' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://yourapp.com/cutshort-events",
    "events": ["candidate.shortlisted", "invite.accepted"],
    "secret": "whsec_3xKpT9mNqL8vR2yD"
  }'

import requests

response = requests.post(
    "https://api.cutshort.io/v1/webhooks",
    json={
        "url": "https://yourapp.com/cutshort-events",
        "events": ["candidate.shortlisted", "invite.accepted"],
        "secret": "whsec_3xKpT9mNqL8vR2yD"
    },
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    }
)
webhook = response.json()
print(f"Registered webhook: {webhook['id']}")

Response

{
  "id": "wh_6kMpL3nR",
  "url": "https://yourapp.com/cutshort-events",
  "events": ["candidate.shortlisted", "invite.accepted"],
  "secret": "whsec_3xKpT9mNqL8vR2yD",
  "status": "active",
  "created_at": "2024-01-15T10:00:00Z"
}

Store the secret field immediately — it is only shown in full at creation time. You will need it to verify webhook signatures on every incoming request.

Delete a Webhook

Permanently remove a registered webhook endpoint. Cutshort will stop delivering events to it immediately.

DELETE https://api.cutshort.io/v1/webhooks/{id}

cURL

curl -X DELETE 'https://api.cutshort.io/v1/webhooks/wh_6kMpL3nR' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Returns 204 No Content on success with an empty response body.

Verifying Signatures

Every webhook request Cutshort sends includes an X-Cutshort-Signature header:

X-Cutshort-Signature: sha256=<hash>

To verify a request is genuine, compute the HMAC-SHA256 of the raw request body using your webhook secret, then compare it to the hash in the header. Always use a constant-time comparison to prevent timing attacks.

import hmac
import hashlib
import json
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()
WEBHOOK_SECRET = "whsec_3xKpT9mNqL8vR2yD"

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

@app.post("/cutshort-events")
async def handle_webhook(request: Request):
    payload = await request.body()
    sig = request.headers.get("X-Cutshort-Signature", "")
    if not verify_webhook(payload, sig, WEBHOOK_SECRET):
        raise HTTPException(status_code=401, detail="Invalid signature")
    event = json.loads(payload)
    # process event...

const crypto = require('crypto');
const express = require('express');

const app = express();

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(`sha256=${expected}`),
    Buffer.from(signature)
  );
}

app.post(
  '/cutshort-events',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const sig = req.headers['x-cutshort-signature'];
    if (!verifyWebhook(req.body, sig, process.env.WEBHOOK_SECRET)) {
      return res.status(401).send('Invalid signature');
    }
    const event = JSON.parse(req.body);
    // process event...
    res.sendStatus(200);
  }
);

Retry Behavior

When a webhook delivery fails — either a non-2xx response or no response within 10 seconds — Cutshort retries the delivery up to 5 times on an exponential schedule:

Attempt	Delay after previous failure
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry	8 hours

After 5 consecutive failures the endpoint is automatically disabled. To re-enable it, either use your Cutshort dashboard or send a PATCH request to /v1/webhooks/{id} with "status": "active".

Overview

Candidates

Jobs

Sourcing

Webhooks — Configure Endpoints, Signatures, and Retries

List Webhooks

Register a Webhook

Request Body

Example Request

Delete a Webhook

Verifying Signatures

Retry Behavior

​List Webhooks

​Register a Webhook

​Request Body

​Example Request

​Delete a Webhook

​Verifying Signatures

​Retry Behavior

List Webhooks

Register a Webhook

Request Body

Example Request

Delete a Webhook

Verifying Signatures

Retry Behavior