Webhooks

Every request goes to your tenant’s own host, https://<tenant id>.atlanticagenticlabs.com, and is scoped to that tenant by row-level security. The examples read AAL_TENANT, AAL_KEY and your Access service token from the environment: see Authentication.

List Webhooks

GET /api/v1/webhooks

Authentication: A person’s session, or a machine key with your Access service token, as the route’s role allows. A route that approves, decides, pays or changes a limit refuses a machine key (person_required).

Status	Meaning
200	OK: the JSON document this route reads.
4XX	Refused: {error, message} with a fixed error code, listed under Errors.

curl

curl "https://$AAL_TENANT.atlanticagenticlabs.com/api/v1/webhooks" \
  -H "Authorization: Bearer $AAL_KEY" \
  -H "CF-Access-Client-Id: $CF_ACCESS_CLIENT_ID" \
  -H "CF-Access-Client-Secret: $CF_ACCESS_CLIENT_SECRET"

Python

import os

import httpx

headers = {
    "Authorization": f"Bearer {os.environ['AAL_KEY']}",
    "CF-Access-Client-Id": os.environ["CF_ACCESS_CLIENT_ID"],
    "CF-Access-Client-Secret": os.environ["CF_ACCESS_CLIENT_SECRET"],
}
r = httpx.get(f"https://{os.environ['AAL_TENANT']}.atlanticagenticlabs.com/api/v1/webhooks", headers=headers)
r.raise_for_status()
print(r.json())

TypeScript

const res = await fetch(
  `https://${process.env.AAL_TENANT}.atlanticagenticlabs.com/api/v1/webhooks`,
  {
    headers: {
      Authorization: `Bearer ${process.env.AAL_KEY}`,
      "CF-Access-Client-Id": process.env.CF_ACCESS_CLIENT_ID!,
      "CF-Access-Client-Secret": process.env.CF_ACCESS_CLIENT_SECRET!,
    },
  },
);
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
console.log(await res.json());

Add Webhook

POST /api/v1/webhooks

Authentication: A person’s session, or a machine key with your Access service token, as the route’s role allows. A route that approves, decides, pays or changes a limit refuses a machine key (person_required).

Status	Meaning
201	Created: the new resource, as JSON.
4XX	Refused: {error, message} with a fixed error code, listed under Errors.

curl

curl -X POST "https://$AAL_TENANT.atlanticagenticlabs.com/api/v1/webhooks" \
  -H "Authorization: Bearer $AAL_KEY" \
  -H "CF-Access-Client-Id: $CF_ACCESS_CLIENT_ID" \
  -H "CF-Access-Client-Secret: $CF_ACCESS_CLIENT_SECRET"

Python

import os

import httpx

headers = {
    "Authorization": f"Bearer {os.environ['AAL_KEY']}",
    "CF-Access-Client-Id": os.environ["CF_ACCESS_CLIENT_ID"],
    "CF-Access-Client-Secret": os.environ["CF_ACCESS_CLIENT_SECRET"],
}
r = httpx.post(f"https://{os.environ['AAL_TENANT']}.atlanticagenticlabs.com/api/v1/webhooks", headers=headers)
r.raise_for_status()
print(r.json())

TypeScript

const res = await fetch(
  `https://${process.env.AAL_TENANT}.atlanticagenticlabs.com/api/v1/webhooks`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.AAL_KEY}`,
      "CF-Access-Client-Id": process.env.CF_ACCESS_CLIENT_ID!,
      "CF-Access-Client-Secret": process.env.CF_ACCESS_CLIENT_SECRET!,
    },
  },
);
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
console.log(await res.json());

Change Webhook

PUT /api/v1/webhooks/{webhook_id}

Authentication: A person’s session, or a machine key with your Access service token, as the route’s role allows. A route that approves, decides, pays or changes a limit refuses a machine key (person_required).

Parameter	In	Type	Required
webhook_id	path	string	yes

Status	Meaning
200	OK: the request was carried out. The answer is JSON.
400	Bad request, bad_query: a path or query parameter, or a body field, is missing or not valid.
4XX	Refused: {error, message} with a fixed error code, listed under Errors.

curl

curl -X PUT "https://$AAL_TENANT.atlanticagenticlabs.com/api/v1/webhooks/WEBHOOK_ID" \
  -H "Authorization: Bearer $AAL_KEY" \
  -H "CF-Access-Client-Id: $CF_ACCESS_CLIENT_ID" \
  -H "CF-Access-Client-Secret: $CF_ACCESS_CLIENT_SECRET"

Python

import os

import httpx

headers = {
    "Authorization": f"Bearer {os.environ['AAL_KEY']}",
    "CF-Access-Client-Id": os.environ["CF_ACCESS_CLIENT_ID"],
    "CF-Access-Client-Secret": os.environ["CF_ACCESS_CLIENT_SECRET"],
}
r = httpx.put(f"https://{os.environ['AAL_TENANT']}.atlanticagenticlabs.com/api/v1/webhooks/WEBHOOK_ID", headers=headers)
r.raise_for_status()
print(r.json())

TypeScript

const res = await fetch(
  `https://${process.env.AAL_TENANT}.atlanticagenticlabs.com/api/v1/webhooks/WEBHOOK_ID`,
  {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${process.env.AAL_KEY}`,
      "CF-Access-Client-Id": process.env.CF_ACCESS_CLIENT_ID!,
      "CF-Access-Client-Secret": process.env.CF_ACCESS_CLIENT_SECRET!,
    },
  },
);
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
console.log(await res.json());

Remove Webhook

DELETE /api/v1/webhooks/{webhook_id}

Authentication: A person’s session, or a machine key with your Access service token, as the route’s role allows. A route that approves, decides, pays or changes a limit refuses a machine key (person_required).

Parameter	In	Type	Required
webhook_id	path	string	yes

Status	Meaning
200	OK: the request was carried out. The answer is JSON.
400	Bad request, bad_query: a path or query parameter, or a body field, is missing or not valid.
4XX	Refused: {error, message} with a fixed error code, listed under Errors.

curl

curl -X DELETE "https://$AAL_TENANT.atlanticagenticlabs.com/api/v1/webhooks/WEBHOOK_ID" \
  -H "Authorization: Bearer $AAL_KEY" \
  -H "CF-Access-Client-Id: $CF_ACCESS_CLIENT_ID" \
  -H "CF-Access-Client-Secret: $CF_ACCESS_CLIENT_SECRET"

Python

import os

import httpx

headers = {
    "Authorization": f"Bearer {os.environ['AAL_KEY']}",
    "CF-Access-Client-Id": os.environ["CF_ACCESS_CLIENT_ID"],
    "CF-Access-Client-Secret": os.environ["CF_ACCESS_CLIENT_SECRET"],
}
r = httpx.delete(f"https://{os.environ['AAL_TENANT']}.atlanticagenticlabs.com/api/v1/webhooks/WEBHOOK_ID", headers=headers)
r.raise_for_status()
print(r.json())

TypeScript

const res = await fetch(
  `https://${process.env.AAL_TENANT}.atlanticagenticlabs.com/api/v1/webhooks/WEBHOOK_ID`,
  {
    method: "DELETE",
    headers: {
      Authorization: `Bearer ${process.env.AAL_KEY}`,
      "CF-Access-Client-Id": process.env.CF_ACCESS_CLIENT_ID!,
      "CF-Access-Client-Secret": process.env.CF_ACCESS_CLIENT_SECRET!,
    },
  },
);
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
console.log(await res.json());

Delivery Log

GET /api/v1/webhooks/{webhook_id}/deliveries

Authentication: A person’s session, or a machine key with your Access service token, as the route’s role allows. A route that approves, decides, pays or changes a limit refuses a machine key (person_required).

Parameter	In	Type	Required
webhook_id	path	string	yes
limit	query	integer	no

Status	Meaning
200	OK: the JSON document this route reads.
400	Bad request, bad_query: a path or query parameter, or a body field, is missing or not valid.
4XX	Refused: {error, message} with a fixed error code, listed under Errors.

curl

curl "https://$AAL_TENANT.atlanticagenticlabs.com/api/v1/webhooks/WEBHOOK_ID/deliveries" \
  -H "Authorization: Bearer $AAL_KEY" \
  -H "CF-Access-Client-Id: $CF_ACCESS_CLIENT_ID" \
  -H "CF-Access-Client-Secret: $CF_ACCESS_CLIENT_SECRET"

Python

import os

import httpx

headers = {
    "Authorization": f"Bearer {os.environ['AAL_KEY']}",
    "CF-Access-Client-Id": os.environ["CF_ACCESS_CLIENT_ID"],
    "CF-Access-Client-Secret": os.environ["CF_ACCESS_CLIENT_SECRET"],
}
r = httpx.get(f"https://{os.environ['AAL_TENANT']}.atlanticagenticlabs.com/api/v1/webhooks/WEBHOOK_ID/deliveries", headers=headers)
r.raise_for_status()
print(r.json())

TypeScript

const res = await fetch(
  `https://${process.env.AAL_TENANT}.atlanticagenticlabs.com/api/v1/webhooks/WEBHOOK_ID/deliveries`,
  {
    headers: {
      Authorization: `Bearer ${process.env.AAL_KEY}`,
      "CF-Access-Client-Id": process.env.CF_ACCESS_CLIENT_ID!,
      "CF-Access-Client-Secret": process.env.CF_ACCESS_CLIENT_SECRET!,
    },
  },
);
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
console.log(await res.json());

Resend

POST /api/v1/webhooks/{webhook_id}/deliveries/{delivery_id}/retry

Authentication: A person’s session, or a machine key with your Access service token, as the route’s role allows. A route that approves, decides, pays or changes a limit refuses a machine key (person_required).

Parameter	In	Type	Required
webhook_id	path	string	yes
delivery_id	path	string	yes

Status	Meaning
202	Accepted: recorded and queued. It is carried out after this answer, not before it.
400	Bad request, bad_query: a path or query parameter, or a body field, is missing or not valid.
4XX	Refused: {error, message} with a fixed error code, listed under Errors.

curl

curl -X POST "https://$AAL_TENANT.atlanticagenticlabs.com/api/v1/webhooks/WEBHOOK_ID/deliveries/DELIVERY_ID/retry" \
  -H "Authorization: Bearer $AAL_KEY" \
  -H "CF-Access-Client-Id: $CF_ACCESS_CLIENT_ID" \
  -H "CF-Access-Client-Secret: $CF_ACCESS_CLIENT_SECRET"

Python

import os

import httpx

headers = {
    "Authorization": f"Bearer {os.environ['AAL_KEY']}",
    "CF-Access-Client-Id": os.environ["CF_ACCESS_CLIENT_ID"],
    "CF-Access-Client-Secret": os.environ["CF_ACCESS_CLIENT_SECRET"],
}
r = httpx.post(f"https://{os.environ['AAL_TENANT']}.atlanticagenticlabs.com/api/v1/webhooks/WEBHOOK_ID/deliveries/DELIVERY_ID/retry", headers=headers)
r.raise_for_status()
print(r.json())

TypeScript

const res = await fetch(
  `https://${process.env.AAL_TENANT}.atlanticagenticlabs.com/api/v1/webhooks/WEBHOOK_ID/deliveries/DELIVERY_ID/retry`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.AAL_KEY}`,
      "CF-Access-Client-Id": process.env.CF_ACCESS_CLIENT_ID!,
      "CF-Access-Client-Secret": process.env.CF_ACCESS_CLIENT_SECRET!,
    },
  },
);
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
console.log(await res.json());

Rotate Secret

POST /api/v1/webhooks/{webhook_id}/rotate-secret

Authentication: A person’s session, or a machine key with your Access service token, as the route’s role allows. A route that approves, decides, pays or changes a limit refuses a machine key (person_required).

Parameter	In	Type	Required
webhook_id	path	string	yes

Status	Meaning
200	OK: the request was carried out. The answer is JSON.
400	Bad request, bad_query: a path or query parameter, or a body field, is missing or not valid.
4XX	Refused: {error, message} with a fixed error code, listed under Errors.

curl

curl -X POST "https://$AAL_TENANT.atlanticagenticlabs.com/api/v1/webhooks/WEBHOOK_ID/rotate-secret" \
  -H "Authorization: Bearer $AAL_KEY" \
  -H "CF-Access-Client-Id: $CF_ACCESS_CLIENT_ID" \
  -H "CF-Access-Client-Secret: $CF_ACCESS_CLIENT_SECRET"

Python

import os

import httpx

headers = {
    "Authorization": f"Bearer {os.environ['AAL_KEY']}",
    "CF-Access-Client-Id": os.environ["CF_ACCESS_CLIENT_ID"],
    "CF-Access-Client-Secret": os.environ["CF_ACCESS_CLIENT_SECRET"],
}
r = httpx.post(f"https://{os.environ['AAL_TENANT']}.atlanticagenticlabs.com/api/v1/webhooks/WEBHOOK_ID/rotate-secret", headers=headers)
r.raise_for_status()
print(r.json())

TypeScript

const res = await fetch(
  `https://${process.env.AAL_TENANT}.atlanticagenticlabs.com/api/v1/webhooks/WEBHOOK_ID/rotate-secret`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.AAL_KEY}`,
      "CF-Access-Client-Id": process.env.CF_ACCESS_CLIENT_ID!,
      "CF-Access-Client-Secret": process.env.CF_ACCESS_CLIENT_SECRET!,
    },
  },
);
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
console.log(await res.json());

Send Test

POST /api/v1/webhooks/{webhook_id}/test

Authentication: A person’s session, or a machine key with your Access service token, as the route’s role allows. A route that approves, decides, pays or changes a limit refuses a machine key (person_required).

Parameter	In	Type	Required
webhook_id	path	string	yes

Status	Meaning
202	Accepted: recorded and queued. It is carried out after this answer, not before it.
400	Bad request, bad_query: a path or query parameter, or a body field, is missing or not valid.
4XX	Refused: {error, message} with a fixed error code, listed under Errors.

curl

curl -X POST "https://$AAL_TENANT.atlanticagenticlabs.com/api/v1/webhooks/WEBHOOK_ID/test" \
  -H "Authorization: Bearer $AAL_KEY" \
  -H "CF-Access-Client-Id: $CF_ACCESS_CLIENT_ID" \
  -H "CF-Access-Client-Secret: $CF_ACCESS_CLIENT_SECRET"

Python

import os

import httpx

headers = {
    "Authorization": f"Bearer {os.environ['AAL_KEY']}",
    "CF-Access-Client-Id": os.environ["CF_ACCESS_CLIENT_ID"],
    "CF-Access-Client-Secret": os.environ["CF_ACCESS_CLIENT_SECRET"],
}
r = httpx.post(f"https://{os.environ['AAL_TENANT']}.atlanticagenticlabs.com/api/v1/webhooks/WEBHOOK_ID/test", headers=headers)
r.raise_for_status()
print(r.json())

TypeScript

const res = await fetch(
  `https://${process.env.AAL_TENANT}.atlanticagenticlabs.com/api/v1/webhooks/WEBHOOK_ID/test`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.AAL_KEY}`,
      "CF-Access-Client-Id": process.env.CF_ACCESS_CLIENT_ID!,
      "CF-Access-Client-Secret": process.env.CF_ACCESS_CLIENT_SECRET!,
    },
  },
);
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
console.log(await res.json());