Edit a destination: name, URL, on/off, dataset filter, request options, alert URL or delivery limits

curl --request PATCH \
  --url https://app.hookie.ai/admin/api/projects/{pid}/destinations/{id} \
  --header 'Content-Type: application/json' \
  --cookie hookie_session= \
  --data '
{
  "name": "<string>",
  "url": "<string>",
  "enabled": true,
  "dataset_filter": [
    "<string>"
  ],
  "timeout_seconds": 15,
  "max_per_second": 500.05,
  "max_concurrency": 50,
  "headers": [
    {
      "name": "<string>",
      "value": "<string>",
      "secret": false
    }
  ],
  "auth": {
    "type": "none"
  },
  "transform": {
    "type": "template",
    "template": "<unknown>"
  },
  "alert_url": "<string>"
}
'

const options = {
  method: 'PATCH',
  headers: {cookie: 'hookie_session=', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    url: '<string>',
    enabled: true,
    dataset_filter: ['<string>'],
    timeout_seconds: 15,
    max_per_second: 500.05,
    max_concurrency: 50,
    headers: [{name: '<string>', value: '<string>', secret: false}],
    auth: {type: 'none'},
    transform: {type: 'template', template: '<unknown>'},
    alert_url: '<string>'
  })
};

fetch('https://app.hookie.ai/admin/api/projects/{pid}/destinations/{id}', 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/{pid}/destinations/{id}"

payload = {
    "name": "<string>",
    "url": "<string>",
    "enabled": True,
    "dataset_filter": ["<string>"],
    "timeout_seconds": 15,
    "max_per_second": 500.05,
    "max_concurrency": 50,
    "headers": [
        {
            "name": "<string>",
            "value": "<string>",
            "secret": False
        }
    ],
    "auth": { "type": "none" },
    "transform": {
        "type": "template",
        "template": "<unknown>"
    },
    "alert_url": "<string>"
}
headers = {
    "cookie": "hookie_session=",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "ok": true,
  "resumed": 123,
  "warning": "<string>"
}

{
  "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>"
}

{
  "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>"
}

{
  "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>"
}

{
  "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>"
}

{
  "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>"
}

{
  "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>"
}

{
  "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>"
}

{
  "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>"
}

PATCH

admin

api

projects

{pid}

destinations

{id}

Edit a destination: name, URL, on/off, dataset filter, request options, alert URL or delivery limits

curl --request PATCH \
  --url https://app.hookie.ai/admin/api/projects/{pid}/destinations/{id} \
  --header 'Content-Type: application/json' \
  --cookie hookie_session= \
  --data '
{
  "name": "<string>",
  "url": "<string>",
  "enabled": true,
  "dataset_filter": [
    "<string>"
  ],
  "timeout_seconds": 15,
  "max_per_second": 500.05,
  "max_concurrency": 50,
  "headers": [
    {
      "name": "<string>",
      "value": "<string>",
      "secret": false
    }
  ],
  "auth": {
    "type": "none"
  },
  "transform": {
    "type": "template",
    "template": "<unknown>"
  },
  "alert_url": "<string>"
}
'

const options = {
  method: 'PATCH',
  headers: {cookie: 'hookie_session=', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    url: '<string>',
    enabled: true,
    dataset_filter: ['<string>'],
    timeout_seconds: 15,
    max_per_second: 500.05,
    max_concurrency: 50,
    headers: [{name: '<string>', value: '<string>', secret: false}],
    auth: {type: 'none'},
    transform: {type: 'template', template: '<unknown>'},
    alert_url: '<string>'
  })
};

fetch('https://app.hookie.ai/admin/api/projects/{pid}/destinations/{id}', 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/{pid}/destinations/{id}"

payload = {
    "name": "<string>",
    "url": "<string>",
    "enabled": True,
    "dataset_filter": ["<string>"],
    "timeout_seconds": 15,
    "max_per_second": 500.05,
    "max_concurrency": 50,
    "headers": [
        {
            "name": "<string>",
            "value": "<string>",
            "secret": False
        }
    ],
    "auth": { "type": "none" },
    "transform": {
        "type": "template",
        "template": "<unknown>"
    },
    "alert_url": "<string>"
}
headers = {
    "cookie": "hookie_session=",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "ok": true,
  "resumed": 123,
  "warning": "<string>"
}

{
  "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>"
}

{
  "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>"
}

{
  "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>"
}

{
  "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>"
}

{
  "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>"
}

{
  "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>"
}

{
  "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>"
}

{
  "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>"
}

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.

Path Parameters

pid

string

required

Project id (UUID) belonging to the caller workspace.

string

required

Destination id.

Body

application/json

At least one of name, url, enabled, dataset_filter, timeout_seconds, max_per_second, max_concurrency, headers, auth, transform or alert_url. null on a limit restores its default. name and url are validated as on create (url must be https). The signing secret does not change with the URL - the signature covers the timestamp and body, not the address; rotate it on its own route. enabled: true also clears a failing destination's streak and any automatic disable (OBS-2), and sends the deliveries it held (the response's resumed).

name

string

Required string length: 1 - 80

url

string<uri>

https only. Refused (409) for a destination that belongs to a customer portal - its URL is the customer's.

enabled

boolean

dataset_filter

string[] | null

SNAKE_CASE on patch (create uses datasetFilter). null, or a list that dedupes to empty, means every dataset.

Maximum array length: 50

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

timeout_seconds

integer | null

Seconds to wait for the receiver's answer before the attempt counts as failed (1-30). null: the default, 10.

Required range: 1 <= x <= 30

max_per_second

number | null

Most deliveries a second to this destination (0.1-1000). null: no limit. A delivery over it waits on the queue for its reserved slot; it is not failed and is not counted as an attempt.

Required range: 0.1 <= x <= 1000

max_concurrency

integer | null

Most requests in flight to this destination at once (1-100). null: no cap. A delivery over it waits on the queue; it is not failed and is not counted as an attempt.

Required range: 1 <= x <= 100

headers

object[] | null

Custom headers sent with every delivery (DLV-7). Replaces the whole list; null clears it. Sent before Hookie's own headers, which always win.

Maximum array length: 20

Show child attributes

auth

object

Authentication (DLV-7), stored AES-256-GCM encrypted and never returned. null or {type:'none'} removes it. On PATCH, the same type with no credential keeps the stored credential (so an API key's header can be renamed without re-entering it).

Option 1
Option 2
Option 3
Option 4

Show child attributes

transform

object

Payload transformation (DLV-7): data, never code. null sends Hookie's envelope {id, dataset, received_at, data}. A template is any JSON value whose string leaves may hold {{path}} placeholders, read from the envelope with the mapping engine's dotted-path reader ({{dataset}}, {{data.customer.email}}, {{$payload}} for the whole envelope); a string that is exactly one placeholder keeps the value's type, an embedded one becomes text (objects as JSON, missing as empty). A mapping builds a flat object, one key per {path, key}, as routing rules do ($submission.id and $submission.received_at are the record's id and time). At most 16 KB serialised. The body is always sent as application/json and Hookie-Signature is computed over it as sent.

Option 1
Option 2

Show child attributes

alert_url

string<uri> | null

OBS-2: a public https URL (no credentials, no private or internal host) that receives one signed POST when Hookie switches this destination off for failing. Body: {type:'destination.disabled', occurred_at, destination:{id,name,url,project_id}, reason, consecutive_dead, failing_since, last_failure}; headers Hookie-Signature (the destination's signing secret, same scheme as a delivery) and Hookie-Alert: destination.disabled. Sent once, never retried, redirects not followed. null or empty removes it.

Response

Updated.

boolean

required

resumed

integer

Present when enabling sent deliveries the destination held while disabled.

warning

string

When a new url points back at this workspace's own ingest - legal, but usually a loop.

Get started

CLI

Guides

API reference

Edit a destination: name, URL, on/off, dataset filter, request options, alert URL or delivery limits

Authorizations

Path Parameters

Body

Response