APPS
Build on GatherUs
with webhooks
Webhooks are how GatherUs talks to the outside world. Whenever something happens at an event. A check-in, a registration, a new gathering, and we send it to your endpoint in real time, so your app can react the moment it matters.
What is a webhook?
A webhook is a message GatherUs sends to a URL you control. Instead of your app repeatedly asking us “has anything changed yet?”, we push the change to you the instant it happens as an HTTP POST request with a JSON body.
Today, webhooks are the single integration surface for GatherUs. All apps in the App registry are built on them. Register one endpoint and you’ll receive a live stream of everything happening across your events.
No polling, no delay. A check-in printed at the door reaches your endpoint in under a second — ideal for live dashboards, name badges, CRMs and matchmaking tools.
Event types
Every webhook carries a event field. Subscribe to just the events you need.
The payload
Every delivery has the same envelope: an event and a payload object whose shape depends on the event. All versions of an event trigger .created .updated .deleted comes with the same payload.
POST https://your-app.com/webhooks/gatherus
{
"payload": {
"id": 29,
"event": {
"id": 8,
"logo": "https://storage.example.com/demo-app/sticker_logos/Demo_Icon-Light-2.png?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=demo-storage%40example-000000.iam.gserviceaccount.com%2F20200101%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20200101T000000Z&X-Goog-Expires=86400&X-Goog-SignedHeaders=host&X-Goog-Signature=0000000000000000000000000000000000000000000000000000000000000000aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaabbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccdddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff33333333333333333333333333333333333333333333333333333333",
"name": "Sample Event",
"image": null,
"series": {
"id": 2,
"name": "Demo Town Halls",
"when": "",
"status": "active",
"checkin_url": "https://community.example.app/qr/11111111-1111-1111-1111-111111111111",
"description": "<p>Sample series description.</p>",
"number_of_events": 3
},
"end_date": "2020-01-03T18:00:00Z",
"event_url": "https://community.example.app/events/8",
"floor_plan": null,
"start_date": "2020-01-01T06:00:00Z",
"checkin_url": "https://community.example.app/qr/22222222-2222-2222-2222-222222222222",
"description": "<p>Sample</p>",
"end_date_utc": "2020-01-03T18:00:00Z",
"start_date_utc": "2020-01-01T06:00:00Z",
"image_thumbnail": null,
"checkin_end_date": null,
"is_private_event": false,
"dymo_label_layout": null,
"checkin_start_date": null,
"number_of_sessions": 0,
"brother_label_layout": null,
"pre_registration_end_date": null,
"requires_pre_registration": false,
"max_number_of_participants": null,
"is_number_of_visits_visible": true,
"pre_registration_start_date": null,
"public_registration_enabled": false
},
"participant": {
"id": 15,
"email": "jane+test2@example.com",
"about_me": "",
"is_active": true,
"last_name": "Last Name",
"first_name": "First Name",
"last_login": null,
"date_joined": "2020-01-01T16:44:25.739574Z",
"linkedin_url": "",
"visits_count": 0,
"profile_visible": "public",
"newsletter_consent": true,
"questionnaire_answers": {
"company": "Sample Corp",
"job-role": "Director",
"what-is-your-primary-industry": [
"Consulting & Professional Services",
"Government, Policy & Defense"
],
"what-is-your-primary-role-in-the-innovation-community": "Large"
}
}
},
"event": "event_checkin.created"
}Respond with any 2xx status to acknowledge receipt. Anything else, or a timeout over 10 seconds, is treated as a failed delivery.
Set it up
- 1. Add your endpoint
In your GatherUs dashboard, go to
Settings → Webhooksand add the HTTPS URL where you’d like to receive events. See more below. - 2. Choose your events
Select the event types you care about, or subscribe to all of them.
- 3. Verify the signature
Use the signing secret shown on setup to confirm each request really came from GatherUs (see below).
- 4. Return 200 and go
Acknowledge fast, then process asynchronously. You’ll see live deliveries in the dashboard log.
Security
Every request includes an x-webhook-signature header: an HMAC-SHA256 of the raw request body, keyed with your endpoint’s signing secret. Recompute it on your side and compare before trusting the payload.
Verify (Node.js)
// raw = the exact request body bytes const expected = "sha256=" + crypto .createHmac("sha256", SIGNING_SECRET) .update(raw) .digest("hex"); const received = req.headers["x-webhook-signature"]; // constant-time compare const ok = received && crypto.timingSafeEqual( Buffer.from(expected), Buffer.from(received) ); if (!ok) { return res.status(401).end(); }
Verify (PHP)
// $raw = file_get_contents("php://input") — the exact request body $expected = "sha256=" . hash_hmac("sha256", $raw, $signingSecret); $received = $_SERVER["HTTP_X_WEBHOOK_SIGNATURE"] ?? ""; if (!hash_equals($expected, $received)) { http_response_code(401); exit; }
Verify (Python)
# raw = the exact request body bytes import hmac, hashlib expected = "sha256=" + hmac.new( SIGNING_SECRET.encode(), raw, hashlib.sha256 ).hexdigest() received = request.headers.get("x-webhook-signature", "") if not hmac.compare_digest(expected, received): abort(401)
Always serve over HTTPS and keep your signing secret out of client-side code.
Manage webhooks in GatherUs
Here’s the plain-English version. A webhook needs two things: a place for GatherUs to send its messages — a web address usually called a webhook catch or endpoint — and a subscription that tells GatherUs which happenings you want to hear about. You set both up from the GatherUs admin. It takes about a minute.
What’s a “webhook catch”? It’s simply a URL that can receive a message. If you don’t have one yet, a free service like webhook.site hands you a URL instantly and shows every message as it arrives — perfect for testing before you build the real thing.
- 1. Add your endpoint
Go to
GatherUs Admin → Webhooks, click theplus (+)button, and paste the URL of your webhook catch — the address where your app or tool listens for messages. - 2. Subscribe to the events you want
UnderEvent typescheck the event types you want to subscribe to. You can leave the ones you’r enot interested in unchecked — other event types are safely ignored, so subscribing to extras does no harm. Then click“Save and continue editing”.
- 3. Copy your Secret key
Once saved, the page reveals aSecret keyCopy it somewhere safe — your app uses it to confirm each message really came from GatherUs (see Security below). Never put it in code that runs in a browser.
Build it with AI
You don’t need to be a developer to build something on top of GatherUs. Today’s AI coding assistants — Claude, Cursor, Replit, Lovable, v0 and friends — can write the whole app for you if you describe what you want and hand them this page. This section has everything you need to get one going.
The trick is that a webhook needs somewhere to live on the web — a running URL, not just code on your laptop. So pick a tool that both writes the code and hosts it for you (or host it yourself), then follow along.
- 1. Pick an AI builder that gives you a live URL
Tools like– Replit– Lovable– v0write your app and deploy it in one place, so you end up with a public URL you can paste into GatherUs. (Chat-only assistants can write the code, but you’ll still need somewhere to run it, which is also possible if you are comfortable with that.)
- 2. Feed it the context
Give the AI this page — copy/paste this link or the specific payload examples for and the signature-verification snippet. That’s the exact shape of the data GatherUs will send, so the AI can build against something real instead of guessing.
- 3. Describe your app in plain language
Say what should happen when someone checks in. “When a check-in arrives, show the guest’s name and company on a big welcome screen,” or “…post a message to our Slack,” or “…add them to a Google Sheet.” Be specific about what you want to see.
- 4. Wire it up to GatherUs
Once your app is deployed, copy its URL and follow Manage webhooks in GatherUs above — paste the URL, subscribe to the event types you want listen for, and give your app the Secret key so it can verify each message.
- 5. Test with a real check-in
Test it out! If nothing happens, open the GatherUs webhook log and your builder’s logs — tell the AI what you see and it’ll help you fix it.
A starter prompt you can paste
Copy this into your AI builder and fill in the brackets. Attach or paste this page when it asks for more detail.
I want to build a small web app that receives GatherUs webhooks. You can find the webhook setup on this url:
https://gatherus.today/support/webhooks/
Please build and deploy an app that: [describe what you want, e.g. "shows the guest's first name and company full-screen for 10 seconds each time someone checks in"]
The input data from the webhooks is[paste the payload examples from the payload examples from this page here]Give me back the public URL to paste into GatherUs, and tell me
where to put my signing secret.
Ideas to build: a live check-in wall for the door, a Slack or Discord “someone just arrived” ping, an auto-printed name badge, a running attendance dashboard, a raffle that draws from tonight’s check-ins, or a sync into your CRM or a Google Sheet. All of them start from the same event_checkin.created event.