Publish a new version of a webhook

curl --request POST \
  --url https://app.hookie.ai/admin/api/projects/{project_id}/webhooks/{id}/versions \
  --header 'Content-Type: application/json' \
  --cookie hookie_session= \
  --data '
{
  "name": "<string>",
  "slug": "<string>",
  "dataset": "<string>",
  "enabled": true,
  "criteria": [
    {
      "path": "<string>",
      "value": "<unknown>",
      "equals": "<unknown>"
    }
  ],
  "mappings": [
    {
      "path": "<string>",
      "key": "<string>"
    }
  ],
  "dedupe_path": "event_id",
  "major": false
}
'

const options = {
  method: 'POST',
  headers: {cookie: 'hookie_session=', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    slug: '<string>',
    dataset: '<string>',
    enabled: true,
    criteria: [{path: '<string>', value: '<unknown>', equals: '<unknown>'}],
    mappings: [{path: '<string>', key: '<string>'}],
    dedupe_path: 'event_id',
    major: false
  })
};

fetch('https://app.hookie.ai/admin/api/projects/{project_id}/webhooks/{id}/versions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://app.hookie.ai/admin/api/projects/{project_id}/webhooks/{id}/versions"

payload = {
    "name": "<string>",
    "slug": "<string>",
    "dataset": "<string>",
    "enabled": True,
    "criteria": [
        {
            "path": "<string>",
            "value": "<unknown>",
            "equals": "<unknown>"
        }
    ],
    "mappings": [
        {
            "path": "<string>",
            "key": "<string>"
        }
    ],
    "dedupe_path": "event_id",
    "major": False
}
headers = {
    "cookie": "hookie_session=",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "id": "<string>",
  "slug": "orders-v1",
  "base_slug": "orders",
  "version": "1",
  "webhook_slug": "aBcXyz0123456789abcdefgh",
  "public_path": "acme-3f9a/orders/aBcXyz0123456789abcdefgh",
  "public_url": "https://app.hookie.ai/acme-3f9a/orders/aBcXyz0123456789abcdefgh"
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

POST

admin

api

projects

{project_id}

webhooks

{id}

versions

Publish a new version of a webhook

curl --request POST \
  --url https://app.hookie.ai/admin/api/projects/{project_id}/webhooks/{id}/versions \
  --header 'Content-Type: application/json' \
  --cookie hookie_session= \
  --data '
{
  "name": "<string>",
  "slug": "<string>",
  "dataset": "<string>",
  "enabled": true,
  "criteria": [
    {
      "path": "<string>",
      "value": "<unknown>",
      "equals": "<unknown>"
    }
  ],
  "mappings": [
    {
      "path": "<string>",
      "key": "<string>"
    }
  ],
  "dedupe_path": "event_id",
  "major": false
}
'

const options = {
  method: 'POST',
  headers: {cookie: 'hookie_session=', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    slug: '<string>',
    dataset: '<string>',
    enabled: true,
    criteria: [{path: '<string>', value: '<unknown>', equals: '<unknown>'}],
    mappings: [{path: '<string>', key: '<string>'}],
    dedupe_path: 'event_id',
    major: false
  })
};

fetch('https://app.hookie.ai/admin/api/projects/{project_id}/webhooks/{id}/versions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://app.hookie.ai/admin/api/projects/{project_id}/webhooks/{id}/versions"

payload = {
    "name": "<string>",
    "slug": "<string>",
    "dataset": "<string>",
    "enabled": True,
    "criteria": [
        {
            "path": "<string>",
            "value": "<unknown>",
            "equals": "<unknown>"
        }
    ],
    "mappings": [
        {
            "path": "<string>",
            "key": "<string>"
        }
    ],
    "dedupe_path": "event_id",
    "major": False
}
headers = {
    "cookie": "hookie_session=",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "id": "<string>",
  "slug": "orders-v1",
  "base_slug": "orders",
  "version": "1",
  "webhook_slug": "aBcXyz0123456789abcdefgh",
  "public_path": "acme-3f9a/orders/aBcXyz0123456789abcdefgh",
  "public_url": "https://app.hookie.ai/acme-3f9a/orders/aBcXyz0123456789abcdefgh"
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

Authorizations

hookie_session

string

required

The console's sealed session cookie, set by WorkOS AuthKit. Mutating requests also require the X-Requested-With CSRF header.

Headers

Idempotency-Key

string

Makes a POST safe to retry for 24 hours: the same key, credential, path and body returns the stored response (Idempotent-Replayed: true) instead of running again. 422 if the key was used for a different request; 409 while the first is in flight.

Required string length: 1 - 255

Path Parameters

project_id

string

required

Project id (UUID) belonging to the caller workspace.

string

required

Id of any existing webhook row sharing the base slug to version.

Body

application/json

A complete webhook spec (same validator as create) plus the optional major flag.

name

string

required

Required string length: 1 - 80

slug

string

required

Must equal the base slug of the webhook named by {id}.

Pattern: ^[a-z0-9][a-z0-9-]{0,46}$

dataset

string

required

Pattern: ^[A-Za-z][A-Za-z0-9_]{0,62}$

enabled

boolean

default:true

criteria

object[]

Maximum array length: 10

Show child attributes

mappings

object[]

Maximum array length: 50

Show child attributes

dedupe_path

string | null

Opt-in (HK-006): the payload field whose value identifies an event, as a mapping path names one (for example "event_id" or "data.id"; not $payload, $submission.id or $submission.received_at). A POST whose body has the same non-empty string, or the same number, there as an earlier POST to this endpoint is answered 200 with that submission's id, idempotent: true and deduplicated_by: "body", and creates no record or run. A missing field, or a value that is neither, deduplicates nothing. An Idempotency-Key header and a provider delivery id still take precedence. The window is the submission's retention: a repeat is deduplicated for as long as the first submission is kept (the plan's retention window), after which the submission is pruned and a repeat is stored again. This is not the 24-hour Idempotency-Key replay on /admin/api. Off when omitted or null. It is set per version (POST .../versions) and cannot be changed with PATCH.

Maximum string length: 200

Example:

"event_id"

major

boolean

default:false

true bumps the major version (2), otherwise the minor is incremented (1.1).

Response

New version created with its own high-entropy public slug (not returned here - read it back from the webhook list) and its own mirror rule. The per-project webhook cap is NOT re-checked on this path.

string

required

slug

string

required

DEPRECATED shape: the versioned readable id, <base_slug>-v<version>. Matches no column and never appears in a URL. Use base_slug + version, or webhook_slug for the URL.

Example:

"orders-v1"

base_slug

string

The readable identity you supplied. NOT the public URL segment. Safe to log.

Example:

"orders"

version

string

Endpoint version within base_slug.

Example:

"1"

webhook_slug

string

The high-entropy public URL segment. THIS IS THE CREDENTIAL — anyone holding it can post events. Never log it.

Example:

"aBcXyz0123456789abcdefgh"

public_path

string

The endpoint's public location, {workspace}/{project}/{webhook_slug}. Pass this straight to a POST; it needs no assembly. It contains the credential, so treat it as a secret.

Example:

"acme-3f9a/orders/aBcXyz0123456789abcdefgh"

public_url

string<uri>

public_path as an absolute URL on this deployment. Contains the credential — treat it as a secret.

Example:

"https://app.hookie.ai/acme-3f9a/orders/aBcXyz0123456789abcdefgh"

Get started

Concepts

CLI

Guides

API reference

Publish a new version of a webhook

Authorizations

Headers

Path Parameters

Body

Response