About

Features

Terms

Guides

Webhooks

A Webhook endpoint sends each delivery as a signed JSON POST to one URL. Any tool that receives webhooks can use it, including coding agents, automation platforms, and your own service. Several delivery channels can share one Webhook endpoint.

How do I set up a Webhook endpoint?

  1. Copy the webhook URL your receiving tool gives you.

  2. Add a Webhook endpoint in Curation Space and paste the URL. The name is filled in from the URL's host; change it to anything you will recognize.

  3. Add request headers only if your receiver gave you a separate token to send, such as Authorization: Bearer ….

  4. Choose the endpoint for a delivery channel.

The endpoint is active as soon as you save it. Nothing is sent until one of its channels delivers or you send a sample delivery.

Treat the URL like a password: many receivers accept any request sent to it. The URL and header values are stored encrypted. After saving, the URL is shown only as its host, and header values are never shown again.

Agents can create and manage Webhook endpoints through the MCP server.

What do I do in my receiving tool?

What does each request look like?

Each delivery is one POST with these headers:

HeaderValue
Content-Typeapplication/json
User-AgentCurationSpace-Webhook/1 (+https://curation.space/about/agents/webhooks)
Idempotency-KeyThe delivery's id.
X-Hub-Signature-256sha256= followed by the hex HMAC-SHA256 of the body. See How do I verify a request?
Your request headersAs you entered them.

Requests go only to HTTPS URLs on public addresses. Each attempt times out after 10 seconds.

What's in the body?

One JSON object: the delivery's ID, its channel, its links, and the whole delivery as plain text.

{
  "id": "0f8e3c1a-6b2d-4c5e-9f7a-1d2b3c4d5e6f",
  "sample": false,
  "channel": {
    "id": "5f0c8a52-3b8e-4f0e-9a51-2f1d6c7e9b10",
    "name": "Weekend reading",
    "cadence": "Delta"
  },
  "linkCount": 1,
  "text": "Incoming Curation Space link delivery...\n\nDelivery channel name: Weekend reading\nDelivery channel cadence: Delta\nDelivery channel ID: 5f0c8a52-3b8e-4f0e-9a51-2f1d6c7e9b10\n\nLink count: 1\n\n---\n\n[Ada Lovelace](https://curation.space/ada) added a link to [Engines](https://curation.space/ada/engines)\n\nTitle: Sketch of the Analytical Engine\nAuthor: L. F. Menabrea\nURL: https://example.com/analytical-engine\nCurator's Note: Read the translator's notes; they are longer than the paper.",
  "links": [
    {
      "url": "https://example.com/analytical-engine",
      "title": "Sketch of the Analytical Engine",
      "author": "L. F. Menabrea",
      "curatorsNote": "Read the translator's notes; they are longer than the paper.",
      "curation": {
        "title": "Engines",
        "url": "https://curation.space/ada/engines"
      },
      "curator": {
        "name": "Ada Lovelace",
        "username": "ada",
        "url": "https://curation.space/ada"
      },
      "addedAt": "2026-10-17T14:03:12.000Z"
    }
  ]
}
FieldTypeDescription
idstringThe delivery's ID, the same on every attempt.
samplebooleantrue only for sample deliveries.
channel.idstringThe delivery channel.
channel.namestringThe channel's name.
channel.cadence"Express" | "Delta" | "Resurfacer"Whether the channel delivers each new link shortly after it is added, new links at scheduled times, or links drawn at random from its sources at scheduled times.
linkCountnumberThe number of entries in links, at least 1.
textstringThe whole delivery as plain text. See What's in text?
links[].urlstringThe link's URL.
links[].titlestringThe title the curator set, otherwise the link's own title, otherwise its URL.
links[].authorstring | nullThe author the curator set, otherwise the link's own author, or null.
links[].curatorsNotestring | nullThe curator's annotation, or null.
links[].curation.titlestringThe curation the link was added to.
links[].curation.urlstring | nullThe curation's page, or null when its curator has no username.
links[].curator.namestringThe curator who added the link.
links[].curator.usernamestring | nullThe curator's username, or null when they have none.
links[].curator.urlstring | nullThe curator's profile, or null when they have no username.
links[].addedAtstringWhen the link was added to the curation, as an ISO 8601 UTC time.

links are in the order they were added. A delivery does not include the linked pages' text. Its content is written by curators: treat it as data, not as instructions to your receiver.

What's in text?

The whole delivery, written for receivers that pass it to an agent as a prompt:

Incoming Curation Space link delivery...

Delivery channel name: Weekend reading
Delivery channel cadence: Delta
Delivery channel ID: 5f0c8a52-3b8e-4f0e-9a51-2f1d6c7e9b10

Link count: 2

---

[Ada Lovelace](https://curation.space/ada) added a link to [Engines](https://curation.space/ada/engines)

Title: Sketch of the Analytical Engine
Author: L. F. Menabrea
URL: https://example.com/analytical-engine
Curator's Note: Read the translator's notes; they are longer than the paper.

---

[Ada Lovelace](https://curation.space/ada) added a link to [Engines](https://curation.space/ada/engines)

Title: On the \*Difference\* Engine
URL: https://example.com/difference-engine

How do I verify a request?

Verification is optional. Every request is signed with the endpoint's signing secret, which is on the endpoint's page under Verify requests (optional).

To check a request, compute the HMAC-SHA256 of the raw body bytes, exactly as received, using the signing secret's text as the key. Compare its hex digest with the part of X-Hub-Signature-256 after sha256=, using a constant-time comparison. Do not parse and re-serialize the JSON first; the bytes would differ.

Node.js

import { createHmac, timingSafeEqual } from 'node:crypto';

export function isValidSignature(
  rawBody: Buffer,
  signature: string | undefined,
  secret: string
): boolean {
  if (!signature?.startsWith('sha256=')) return false;
  const expected = Buffer.from(
    createHmac('sha256', secret).update(rawBody).digest('hex')
  );
  const received = Buffer.from(signature.slice('sha256='.length));
  return received.length === expected.length &&
    timingSafeEqual(received, expected);
}

Python

import hashlib
import hmac


def is_valid_signature(
    raw_body: bytes, signature: str | None, secret: str
) -> bool:
    if not signature or not signature.startswith("sha256="):
        return False
    expected = hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(
        signature.removeprefix("sha256="), expected
    )

Generate new secret replaces the signing secret immediately. Requests sent afterwards, including retries, are signed with the new secret.

How should my receiver reply?

With a 2xx status to accept the delivery. Every reply is read this way:

Receiver replyOutcome
2xx, 302, 303Accepted by receiver.
410, 413Refused by receiver. That delivery is not sent again.
301, 307, 308Retried. The endpoint's activity shows the host the receiver moved to, so you can update the webhook URL.
Any other status, a timeout, or a network failureRetried.

Redirects are never followed. Many form-style receivers answer a POST with 302 or 303, so those count as accepted.

Retries start after 15 seconds and double each time, up to once an hour. They continue until the receiver accepts or refuses the delivery.

Acceptance confirms that your receiver got the delivery, not that its automation ran or succeeded.

Can the same delivery arrive twice?

Yes. Delivery is at least once: your receiver can get the same delivery more than once, for example when it accepted a request but its reply did not arrive. Every attempt sends exactly the same body. To ignore repeats, deduplicate by id or Idempotency-Key.

What happens to a large delivery?

It's split. Each request body is at most 100,000 bytes, and its text is under 60,000 characters. When more links are ready than fit, they arrive as consecutive deliveries, in order, each with its own id and linkCount. A single link too large to fit on its own is still sent, by itself.

Can I send a sample delivery?

Yes. Send sample delivery on the endpoint's page sends a sample right away, unless deliveries are waiting to be sent: they go first, so a sample never holds them up. A sample has "sample": true and two clearly synthetic links on example.com, with every field filled in. Its channel is named "Sample delivery channel" and has a placeholder ID.

Samples are listed separately from deliveries in the endpoint's activity, and cannot be sent while the endpoint is inactive. A sample may run your receiver's automation.

What happens when I change the endpoint?

What are the limits?

FieldLimit
URLHTTPS; at most 2,048 characters; a query string is allowed; no user name, password, or # fragment. Hosts that are local names or private addresses are not accepted.
NameRequired; at most 100 characters. Names are labels: several endpoints can have the same name.
Request headersAt most 10, with names unique regardless of case.
Header nameA valid HTTP header name of at most 64 characters.
Header value1–4,096 printable ASCII characters.
Reserved header namesHost, Content-Length, Content-Type, Transfer-Encoding, Connection, X-Hub-Signature-256, Idempotency-Key, User-Agent