Webhooks, API and MCP
Two ways to get your event’s replies out of The Details: webhooks that push each reply, sign-up and check-in to your server as it happens, and a read-only API for your events and guest lists. Both come with the event pass, and so does the MCP server, which lets Claude or ChatGPT read and manage your events. For Zapier, Make, n8n and Google Sheets, start with the step-by-step guide.
Webhooks
Add an endpoint on the event’s Integrations tab: an https address and the event types it wants. Each event can have 5. We send a POST with a JSON body to it for each happening, one request per endpoint.
Headers
| Header | Value |
|---|---|
Content-Type | application/json |
User-Agent | TheDetails-Webhooks/1 |
X-TheDetails-Event | The event type, such as reply.created |
X-TheDetails-Delivery | The delivery’s id (whd_…), the same on every retry and on a resend |
X-TheDetails-Signature | t=<unix seconds>,v1=<hex HMAC-SHA256>: see Signatures |
The body
| Field | What it is |
|---|---|
id | evt_…: the happening. The same on every retry, every endpoint and a resend, so you can skip one you already handled. |
type | One of the event types below. |
created_at | When it happened, ISO 8601 in UTC. |
event | { id, slug, headline }: which of your events. |
data | Depends on the type. What you see on your guest list: names, the email as stored, replies to each part, answers by question. |
Field names are snake_case and stay as they are; new fields may be added. Times are UTC; event times also come as *_local wall-clock values with the event’s timezone. The data is read when each delivery is sent, so a retry or a resend carries it as it is then.
Event types
reply.created
A household (an invitation, or someone who replied through the open form) replies for the first time. data.household has everyone on it, with their reply to each part and their answers.
{
"id": "evt_3hQf8Zk2LmN0pR5s",
"type": "reply.created",
"created_at": "2027-03-02T15:04:05.000Z",
"event": {
"id": "k2Jx9wQ4bT7rNc1LmZp3Aa",
"slug": "spring-fundraiser-dinner-q7k2",
"headline": "Spring Fundraiser Dinner"
},
"data": {
"household": {
"id": "hh_4f9c2a7e1b3d5f60",
"label": "Maya and Sam Okafor",
"email": "maya@example.com",
"status": null,
"ticket": null,
"tags": [
"Board"
],
"created_at": "2027-02-20T19:12:00.000Z",
"guests": [
{
"id": "g_8b1e0c4d2a6f3e95",
"household_id": "hh_4f9c2a7e1b3d5f60",
"first_name": "Maya",
"last_name": "Okafor",
"is_child": false,
"is_plus_one": false,
"replies": [
{
"sub_event_id": "dinner",
"sub_event": "Dinner",
"status": "yes"
}
],
"answers": [
{
"question_id": "meal",
"question": "Meal",
"answer": "Fish"
}
]
},
{
"id": "g_2d7f5a9c0e1b4d63",
"household_id": "hh_4f9c2a7e1b3d5f60",
"first_name": "Sam",
"last_name": "Okafor",
"is_child": false,
"is_plus_one": false,
"replies": [
{
"sub_event_id": "dinner",
"sub_event": "Dinner",
"status": "yes"
}
],
"answers": [
{
"question_id": "meal",
"question": "Meal",
"answer": "Vegetarian"
},
{
"question_id": "diet",
"question": "Allergies or dietary needs",
"answer": "No nuts"
}
]
}
]
}
}
}reply.updated
A household that had replied changes its reply. The same shape as reply.created, as it stands now.
{
"id": "evt_3hQf8Zk2LmN0pR5s",
"type": "reply.updated",
"created_at": "2027-03-02T15:04:05.000Z",
"event": {
"id": "k2Jx9wQ4bT7rNc1LmZp3Aa",
"slug": "spring-fundraiser-dinner-q7k2",
"headline": "Spring Fundraiser Dinner"
},
"data": {
"household": {
"id": "hh_4f9c2a7e1b3d5f60",
"label": "Maya and Sam Okafor",
"email": "maya@example.com",
"status": null,
"ticket": null,
"tags": [
"Board"
],
"created_at": "2027-02-20T19:12:00.000Z",
"guests": [
{
"id": "g_8b1e0c4d2a6f3e95",
"household_id": "hh_4f9c2a7e1b3d5f60",
"first_name": "Maya",
"last_name": "Okafor",
"is_child": false,
"is_plus_one": false,
"replies": [
{
"sub_event_id": "dinner",
"sub_event": "Dinner",
"status": "yes"
}
],
"answers": [
{
"question_id": "meal",
"question": "Meal",
"answer": "Fish"
}
]
},
{
"id": "g_2d7f5a9c0e1b4d63",
"household_id": "hh_4f9c2a7e1b3d5f60",
"first_name": "Sam",
"last_name": "Okafor",
"is_child": false,
"is_plus_one": false,
"replies": [
{
"sub_event_id": "dinner",
"sub_event": "Dinner",
"status": "yes"
}
],
"answers": [
{
"question_id": "meal",
"question": "Meal",
"answer": "Vegetarian"
},
{
"question_id": "diet",
"question": "Allergies or dietary needs",
"answer": "No nuts"
}
]
}
]
}
}
}signup.claimed
Someone takes something on the sign-up sheet or books a time, or changes how many or their note.
{
"id": "evt_3hQf8Zk2LmN0pR5s",
"type": "signup.claimed",
"created_at": "2027-03-02T15:04:05.000Z",
"event": {
"id": "k2Jx9wQ4bT7rNc1LmZp3Aa",
"slug": "spring-fundraiser-dinner-q7k2",
"headline": "Spring Fundraiser Dinner"
},
"data": {
"item": {
"id": "s_X1y2Z3a4B5c6D7e8",
"name": "Set-up crew",
"note": "Tables and chairs",
"quantity": 6,
"slot": {
"starts_at": "2027-04-17T21:00:00.000Z",
"starts_at_local": "2027-04-17T16:00",
"ends_at": "2027-04-17T23:00:00.000Z",
"ends_at_local": "2027-04-17T18:00",
"timezone": "America/Chicago"
}
},
"household": {
"id": "hh_4f9c2a7e1b3d5f60",
"label": "Maya and Sam Okafor",
"email": "maya@example.com"
},
"count": 1,
"note": "Bringing a dolly"
}
}signup.released
Someone takes their name off something, or the host does. count is what they held before.
{
"id": "evt_3hQf8Zk2LmN0pR5s",
"type": "signup.released",
"created_at": "2027-03-02T15:04:05.000Z",
"event": {
"id": "k2Jx9wQ4bT7rNc1LmZp3Aa",
"slug": "spring-fundraiser-dinner-q7k2",
"headline": "Spring Fundraiser Dinner"
},
"data": {
"item": {
"id": "s_X1y2Z3a4B5c6D7e8",
"name": "Set-up crew",
"note": "Tables and chairs",
"quantity": 6,
"slot": {
"starts_at": "2027-04-17T21:00:00.000Z",
"starts_at_local": "2027-04-17T16:00",
"ends_at": "2027-04-17T23:00:00.000Z",
"ends_at_local": "2027-04-17T18:00",
"timezone": "America/Chicago"
}
},
"household": {
"id": "hh_4f9c2a7e1b3d5f60",
"label": "Maya and Sam Okafor",
"email": "maya@example.com"
},
"count": 1,
"note": ""
}
}guest.checked_in
A guest is checked in at the door, by you or a door helper. One per person. sub_event is null when a registration entry is checked in on the entrant list.
{
"id": "evt_3hQf8Zk2LmN0pR5s",
"type": "guest.checked_in",
"created_at": "2027-03-02T15:04:05.000Z",
"event": {
"id": "k2Jx9wQ4bT7rNc1LmZp3Aa",
"slug": "spring-fundraiser-dinner-q7k2",
"headline": "Spring Fundraiser Dinner"
},
"data": {
"guest": {
"id": "g_8b1e0c4d2a6f3e95",
"household_id": "hh_4f9c2a7e1b3d5f60",
"first_name": "Maya",
"last_name": "Okafor",
"is_child": false,
"is_plus_one": false,
"replies": [
{
"sub_event_id": "dinner",
"sub_event": "Dinner",
"status": "yes"
}
],
"answers": [
{
"question_id": "meal",
"question": "Meal",
"answer": "Fish"
}
]
},
"household": {
"id": "hh_4f9c2a7e1b3d5f60",
"label": "Maya and Sam Okafor",
"email": "maya@example.com"
},
"sub_event": {
"id": "dinner",
"name": "Dinner"
},
"checked_in_at": "2027-04-17T23:41:10.000Z"
}
}registration.waitlisted
A registration lands on the waitlist because the places are full.
{
"id": "evt_3hQf8Zk2LmN0pR5s",
"type": "registration.waitlisted",
"created_at": "2027-03-02T15:04:05.000Z",
"event": {
"id": "k2Jx9wQ4bT7rNc1LmZp3Aa",
"slug": "spring-fundraiser-dinner-q7k2",
"headline": "Spring Fundraiser Dinner"
},
"data": {
"household": {
"id": "hh_4f9c2a7e1b3d5f60",
"label": "Maya and Sam Okafor",
"email": "maya@example.com",
"status": "waitlist",
"ticket": null,
"tags": [
"Board"
],
"created_at": "2027-02-20T19:12:00.000Z",
"guests": [
{
"id": "g_8b1e0c4d2a6f3e95",
"household_id": "hh_4f9c2a7e1b3d5f60",
"first_name": "Maya",
"last_name": "Okafor",
"is_child": false,
"is_plus_one": false,
"replies": [
{
"sub_event_id": "dinner",
"sub_event": "Dinner",
"status": "yes"
}
],
"answers": [
{
"question_id": "meal",
"question": "Meal",
"answer": "Fish"
}
]
},
{
"id": "g_2d7f5a9c0e1b4d63",
"household_id": "hh_4f9c2a7e1b3d5f60",
"first_name": "Sam",
"last_name": "Okafor",
"is_child": false,
"is_plus_one": false,
"replies": [
{
"sub_event_id": "dinner",
"sub_event": "Dinner",
"status": "yes"
}
],
"answers": [
{
"question_id": "meal",
"question": "Meal",
"answer": "Vegetarian"
},
{
"question_id": "diet",
"question": "Allergies or dietary needs",
"answer": "No nuts"
}
]
}
]
}
}
}registration.promoted
A registration moves up from the waitlist into a place.
{
"id": "evt_3hQf8Zk2LmN0pR5s",
"type": "registration.promoted",
"created_at": "2027-03-02T15:04:05.000Z",
"event": {
"id": "k2Jx9wQ4bT7rNc1LmZp3Aa",
"slug": "spring-fundraiser-dinner-q7k2",
"headline": "Spring Fundraiser Dinner"
},
"data": {
"household": {
"id": "hh_4f9c2a7e1b3d5f60",
"label": "Maya and Sam Okafor",
"email": "maya@example.com",
"status": "registered",
"ticket": null,
"tags": [
"Board"
],
"created_at": "2027-02-20T19:12:00.000Z",
"guests": [
{
"id": "g_8b1e0c4d2a6f3e95",
"household_id": "hh_4f9c2a7e1b3d5f60",
"first_name": "Maya",
"last_name": "Okafor",
"is_child": false,
"is_plus_one": false,
"replies": [
{
"sub_event_id": "dinner",
"sub_event": "Dinner",
"status": "yes"
}
],
"answers": [
{
"question_id": "meal",
"question": "Meal",
"answer": "Fish"
}
]
},
{
"id": "g_2d7f5a9c0e1b4d63",
"household_id": "hh_4f9c2a7e1b3d5f60",
"first_name": "Sam",
"last_name": "Okafor",
"is_child": false,
"is_plus_one": false,
"replies": [
{
"sub_event_id": "dinner",
"sub_event": "Dinner",
"status": "yes"
}
],
"answers": [
{
"question_id": "meal",
"question": "Meal",
"answer": "Vegetarian"
},
{
"question_id": "diet",
"question": "Allergies or dietary needs",
"answer": "No nuts"
}
]
}
]
}
}
}test
Sent by “Send a test event” on the Integrations tab. data holds only a message.
{
"id": "evt_3hQf8Zk2LmN0pR5s",
"type": "test",
"created_at": "2027-03-02T15:04:05.000Z",
"event": {
"id": "k2Jx9wQ4bT7rNc1LmZp3Aa",
"slug": "spring-fundraiser-dinner-q7k2",
"headline": "Spring Fundraiser Dinner"
},
"data": {
"message": "A test event from The Details. Your endpoint received it."
}
}Checking the signature
Each endpoint has its own secret (whsec_…), on the Integrations tab. We sign <t>.<raw body> with HMAC-SHA256, using the whole secret as the key, and send the hex digest as v1. To check it: take t and v1 from the header, compute the same HMAC over the body exactly as it arrived, compare in constant time, and refuse a t more than five minutes old. Roll the secret from the tab if it gets out; the old one stops at once.
const crypto = require('node:crypto')
// secret: the endpoint's signing secret (whsec_…), from the Integrations tab.
// rawBody: the request body exactly as it arrived, as a string (before JSON.parse).
// header: the X-TheDetails-Signature header, "t=<seconds>,v1=<hex>".
function verify(secret, rawBody, header, toleranceSeconds = 300) {
const parts = Object.fromEntries(header.split(',').map((p) => p.trim().split('=')))
const t = Number(parts.t)
if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false
const expected = crypto.createHmac('sha256', secret).update(t + '.' + rawBody).digest()
const given = Buffer.from(parts.v1 || '', 'hex')
return given.length === expected.length && crypto.timingSafeEqual(given, expected)
}// Express: keep the raw body for the check, then parse it yourself.
app.post('/thedetails', express.text({ type: 'application/json' }), (req, res) => {
if (!verify(process.env.THEDETAILS_SECRET, req.body, req.get('X-TheDetails-Signature') || '')) {
return res.status(400).send('bad signature')
}
const event = JSON.parse(req.body)
// event.id is the same on every retry: skip ones you already handled.
res.sendStatus(200)
})import hashlib
import hmac
import time
# secret: the endpoint's signing secret (whsec_...). raw_body: the request body as bytes,
# exactly as it arrived. header: the X-TheDetails-Signature header.
def verify(secret: str, raw_body: bytes, header: str, tolerance: int = 300) -> bool:
parts = dict(p.strip().split("=", 1) for p in header.split(",") if "=" in p)
try:
t = int(parts.get("t", ""))
except ValueError:
return False
if abs(time.time() - t) > tolerance:
return False
expected = hmac.new(secret.encode(), str(t).encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", ""))Retries and turning off
- Answer with any 2xx within 10 seconds. We don’t read the body you send back.
- Anything else is a failure: another status, a redirect (we don’t follow them), a timeout or no connection. We try again after 30 seconds, 2 minutes, 10 minutes, 30 minutes, 2 hours: 6 tries in all.
- If 50 deliveries in a row fail all their tries, the endpoint turns off and the event’s owner gets one email. Turning it back on starts the count again. A delivery that works resets it.
- The tab keeps the last 100 tries per endpoint (time, type, try, status, time taken; never the bodies), with Resend on failed ones.
- Deliveries stop at once when an endpoint is turned off or deleted, when the event no longer has the pass, or when we take the event offline.
- A Google Apps Script web app answers 302 after it runs; from script.google.com that counts as delivered.
API
Read-only, JSON over https. Make a key in your account settings, under API keys: for all your events or the ones you choose. It’s shown once (td_live_…); we keep only a hash. Send it as a bearer token. A key reads events you made (not ones you co-host) that have the event pass.
curl https://thedetails.page/api/v1/events \
-H "Authorization: Bearer td_live_…"| GET | Returns |
|---|---|
/api/v1/events | Your events, newest first. |
/api/v1/events/:id | One event, as { data: event }. |
/api/v1/events/:id/guests | Every person on the guest list, with their household. |
/api/v1/events/:id/replies | Households that replied, as reply.created sends them. |
/api/v1/events/:id/signups | Who took what on the sign-up sheet. |
/api/v1/events/:id/checkins | Who was checked in, and when. |
Pages
Lists come as { data: [...], next_cursor }. Ask for up to 100 at a time with ?limit= (default 50); while next_cursor isn’t null, pass it back as ?cursor= for the next page.
{
"data": [
{
"id": "k2Jx9wQ4bT7rNc1LmZp3Aa",
"slug": "spring-fundraiser-dinner-q7k2",
"headline": "Spring Fundraiser Dinner",
"type": "party",
"published": true,
"url": "https://thedetails.page/e/spring-fundraiser-dinner-q7k2",
"timezone": "America/Chicago",
"reply_by": "2027-04-01",
"registration": null,
"sub_events": [
{
"id": "dinner",
"name": "Dinner",
"starts_at": "2027-04-17T23:30:00.000Z",
"starts_at_local": "2027-04-17T18:30",
"ends_at": "2027-04-18T03:00:00.000Z",
"ends_at_local": "2027-04-17T22:00",
"timezone": "America/Chicago",
"venue": {
"name": "Riverside Hall",
"address": "200 River St, Austin, TX"
}
}
],
"questions": [
{
"id": "meal",
"label": "Meal",
"kind": "choice",
"per_guest": true
},
{
"id": "diet",
"label": "Allergies or dietary needs",
"kind": "text",
"per_guest": true
}
],
"created_at": "2027-02-01T10:00:00.000Z",
"updated_at": "2027-03-02T15:04:05.000Z"
}
],
"next_cursor": null
}{
"data": [
{
"id": "g_8b1e0c4d2a6f3e95",
"household_id": "hh_4f9c2a7e1b3d5f60",
"first_name": "Maya",
"last_name": "Okafor",
"is_child": false,
"is_plus_one": false,
"replies": [
{
"sub_event_id": "dinner",
"sub_event": "Dinner",
"status": "yes"
}
],
"answers": [
{
"question_id": "meal",
"question": "Meal",
"answer": "Fish"
}
],
"household": {
"id": "hh_4f9c2a7e1b3d5f60",
"label": "Maya and Sam Okafor",
"email": "maya@example.com",
"status": null,
"tags": [
"Board"
]
}
}
],
"next_cursor": "MDAwMDE4MDk..."
}{
"data": [
{
"item": {
"id": "s_X1y2Z3a4B5c6D7e8",
"name": "Set-up crew",
"note": "Tables and chairs",
"quantity": 6,
"slot": {
"starts_at": "2027-04-17T21:00:00.000Z",
"starts_at_local": "2027-04-17T16:00",
"ends_at": "2027-04-17T23:00:00.000Z",
"ends_at_local": "2027-04-17T18:00",
"timezone": "America/Chicago"
}
},
"household": {
"id": "hh_4f9c2a7e1b3d5f60",
"label": "Maya and Sam Okafor",
"email": "maya@example.com"
},
"count": 1,
"note": "Bringing a dolly"
}
],
"next_cursor": null
}{
"data": [
{
"guest": {
"id": "g_8b1e0c4d2a6f3e95",
"household_id": "hh_4f9c2a7e1b3d5f60",
"first_name": "Maya",
"last_name": "Okafor",
"is_child": false,
"is_plus_one": false,
"replies": [
{
"sub_event_id": "dinner",
"sub_event": "Dinner",
"status": "yes"
}
],
"answers": [
{
"question_id": "meal",
"question": "Meal",
"answer": "Fish"
}
]
},
"household": {
"id": "hh_4f9c2a7e1b3d5f60",
"label": "Maya and Sam Okafor",
"email": "maya@example.com"
},
"sub_event": {
"id": "dinner",
"name": "Dinner"
},
"checked_in_at": "2027-04-17T23:41:10.000Z"
}
],
"next_cursor": null
}Errors and limits
Errors come as { "error": { "code", "message" } }. Each key may make 60 requests a minute; past that you get 429 with Retry-After in seconds.
| Status | code | When |
|---|---|---|
| 400 | invalid_request | A limit outside 1 to 100, or a cursor we didn’t give. |
| 401 | unauthorized | No key, or one that’s unknown or revoked. |
| 403 | pass_required | The event doesn’t have the event pass. |
| 403 | out_of_scope | The key is for other events. |
| 403 | forbidden | The account can’t use The Details right now. |
| 404 | not_found | No such event (or not yours, or taken offline), or no such path. |
| 405 | method_not_allowed | Anything but GET. Writes will come later. |
| 429 | rate_limited | Too many requests; wait Retry-After seconds. |
Responses are never cached and carry no CORS headers: call the API from a server, not a browser, so the key stays secret.
MCP for Claude and ChatGPT
Connect The Details to an AI app that supports the Model Context Protocol, such as Claude or ChatGPT, and ask it about your events in your own words: who hasn’t replied, how many said yes to dinner, add the Lees with two kids, send a reminder. We run no AI ourselves. The app you connect does the asking and calls our tools, as you, on events with the event pass.
https://thedetails.page/mcp/hostConnecting
- In your AI app, find where it adds a custom connector or MCP server (in Claude and ChatGPT it’s in the settings; the exact place and which plans have it change over time).
- Paste the server address above. There’s no key to copy: the app finds our sign-in on its own (OAuth 2.1).
- Your browser opens The Details. Sign in if you aren’t already, read what the app asks for, and choose Allow.
- Back in the app, ask about your events. Before it changes anything, a good app asks you to confirm.
What it may do
| Access | What it allows |
|---|---|
read | Read your events and guest lists. Always on. |
write | Make changes: add and edit guests, send reminders, add sign-up items, change the reply-by date. A separate box on the consent page, on unless you untick it. |
It works on the events you own or co-host that have the event pass; on others, every tool but list_events says the event needs the pass. It can’t delete anything, take payments or change your account. Changes land on the event’s history as made from a connected app. Names, answers and notes from guests reach the app as data, labelled as written by guests.
Tools
| Tool | Needs | What it does |
|---|---|---|
list_events | read | Your events (owned and co-hosted), and which have the event pass. |
get_event | read | One event: its parts, questions, reply-by date and guest count. |
guest_list | read | Households and people with replies and answers. Filters: reply, part, name or email, table, tag. 50 a page, up to 200. |
reply_counts | read | Yes, no and no reply for each part. |
signups | read | The sign-up sheet’s items and slots, and who took each. |
checkin_status | read | Expected and checked-in people for each part. |
poll_results | read | The date poll’s counts and best options. |
feedback_results | read | The feedback survey’s answers (anonymous stays anonymous). |
add_guest | write | Add a household with its people, within the guest limit. |
update_guest | write | Edit a household’s names, email, plus-ones and tags, add people, or record their replies. |
send_reminder | write | Email everyone with an address who hasn’t replied (50 a call, the usual limits). |
add_signup_item | write | Add a thing to bring or a time slot to the sign-up sheet. |
add_shifts | write | Make volunteer shifts for roles over one or more days. |
set_reply_by | write | Change the reply-by date in the draft (guests see it once you publish). |
Disconnecting
Your account settings list each connected app under Connected apps, with what it may do and when it was last used. Disconnect stops it at once. Access tokens last an hour and the app renews them; a connection nobody uses for 30 days needs connecting again.
For client developers
| Transport | Streamable HTTP, stateless, JSON responses |
| Protected resource metadata | /.well-known/oauth-protected-resource/mcp/host |
| Authorization server metadata | /.well-known/oauth-authorization-server |
| Registration | POST /oauth/register: public clients only (token_endpoint_auth_method: none); redirect URIs on https, or http on localhost or 127.0.0.1 |
| Authorization | /oauth/authorize: authorization code with PKCE (S256 only); the redirect URI must match exactly |
| Tokens | POST /oauth/token: codes last 10 minutes and work once; refresh tokens rotate, and reusing an old one ends the connection |
| Revocation | POST /oauth/revoke |
| Limits | 120 requests a minute per account; tool results are JSON text |