Webhooks
A webhook tells another system when something happens in your community. You give Somiti a web address and pick the events you care about, and Somiti sends that address a short message (an HTTP POST with JSON) each time one of them happens. Zapier, Make and most website tools can receive them, so you can add new members to a spreadsheet or update a ride calendar on your website without copying anything by hand.
Only admins can set up webhooks. Go to Settings, click the Integrations tab, then Webhooks.
Set up a webhook
- Click Add Webhook (on the Webhooks page, or in the Custom Webhooks box on the Integrations page).
- Fill in:
- Name: up to 100 characters, so you can tell your webhooks apart.
- Endpoint URL: the address that should receive the messages, from Zapier, Make or your developer.
- Description: optional.
- Under Events to Subscribe, check at least one event. They’re grouped into Members, Memberships, Events, EventRegistrations, Payments and Announcements. See Which events Somiti sends before you pick: a few of them aren’t sent yet.
- Leave Status on Active.
- Click Create Webhook.
You’ll land on the webhook’s page with “Webhook created successfully.” Somiti makes a signing secret for it automatically. Click Send Test to check the address works.
Use an address that starts with https:// so the messages are encrypted on the way. Somiti only delivers to addresses on the public internet: an address on your own network, like a computer in the clubhouse, fails with “does not resolve to a public address”.
Check a webhook’s deliveries
Click a webhook’s name on the Webhooks page to open it.
- The signing secret your system uses to check messages came from Somiti.
- The events this webhook sends.
- The share of finished deliveries that your system accepted.
Statistics counts deliveries that have finished, either delivered or failed for good. A delivery still being retried isn’t counted yet.
Further down, Recent Deliveries lists every message, newest first, 20 to a page:
- Failed means all three attempts were refused.
- What your system answered. 200 to 299 counts as delivered.
Each row shows:
- Event: the event name, and its id underneath.
- Status: Pending (not sent yet), Delivered, Retrying (1/3) or (2/3), or Failed.
- Response: the code your system sent back, or the reason Somiti couldn’t reach it.
- Duration: how long your system took to answer.
- Time: when the event happened, in UTC.
Send a test
Click Send Test at the top of the webhook’s page. Somiti sends this right away, while you wait:
{
"id": "test_3f9a1c2b7d4e8f60",
"type": "test",
"created_at": "2026-10-31T14:00:00Z",
"data": {
"test": true,
"message": "This is a test webhook from Somiti",
"community": "Your Community Name",
"timestamp": "2026-10-31T14:00:00Z"
}
}
If your system answers with a code from 200 to 299, you’ll see “Test webhook delivered successfully!” Otherwise you’ll see “Test webhook failed. Check the delivery log for details.” and the reason shows in Recent Deliveries. Test messages show up in Recent Deliveries and count in Statistics, and a failed test is retried like any other delivery.
Find or change the signing secret
Somiti signs every message with the webhook’s secret so your system can check it really came from Somiti (see Verify webhook signatures).
- To see it: click Reveal. The secret shows for three seconds. Select it and copy it yourself while it’s showing; the button doesn’t copy it for you.
- To replace it: click Regenerate and click OK to confirm. The new secret appears in a yellow box with a Copy button. The old secret stops working straight away, so update your system right after.
Regenerate the secret if you think someone else has seen it.
Edit, pause or delete a webhook
On the webhook’s page:
- Edit changes the name, address, description, events or status. Click Update Webhook to save.
- To pause it, click Edit, choose Inactive and click Update Webhook. Somiti stops sending until you set it back to Active.
- Delete removes the webhook and its delivery history after you click OK to confirm.
Verify webhook signatures
Somiti signs every delivery with HMAC-SHA256 so you can confirm the request actually came from Somiti and hasn’t been tampered with.
The signature covers the timestamp and the payload body:
HMAC-SHA256(secret, timestamp + "." + payload)
The result is sent in the X-Webhook-Signature header as sha256=<hex-encoded-signature>.
To verify:
- Extract the
X-Webhook-TimestampandX-Webhook-Signatureheaders. - Get the raw request body (the JSON payload).
- Concatenate:
timestamp + "." + payload. - Compute HMAC-SHA256 using your webhook secret.
- Compare with the provided signature using constant-time comparison.
- Optionally, reject requests with timestamps older than 5 minutes to prevent replay attacks.
Ruby
require 'openssl'
def verify_webhook(request, secret)
timestamp = request.headers['X-Webhook-Timestamp']
signature = request.headers['X-Webhook-Signature']
payload = request.body.read
# Check timestamp to prevent replay attacks
request_time = Time.at(timestamp.to_i)
if (Time.current - request_time).abs > 300 # 5 minutes
return false
end
# Compute expected signature
signature_payload = "#{timestamp}.#{payload}"
expected = "sha256=" + OpenSSL::HMAC.hexdigest(
OpenSSL::Digest.new('sha256'),
secret,
signature_payload
)
# Constant-time comparison
ActiveSupport::SecurityUtils.secure_compare(expected, signature)
end
Node.js
const crypto = require('crypto');
const express = require('express');
// Capture the raw body before Express parses it.
// Add this middleware BEFORE your webhook route.
app.use('/webhooks', express.json({
verify: (req, res, buf) => { req.rawBody = buf.toString('utf-8'); }
}));
function verifyWebhook(req, secret) {
const timestamp = req.headers['x-webhook-timestamp'];
const signature = req.headers['x-webhook-signature'];
const payload = req.rawBody;
// Check timestamp to prevent replay attacks
const requestTime = new Date(parseInt(timestamp) * 1000);
const now = new Date();
if (Math.abs(now - requestTime) > 300000) { // 5 minutes
return false;
}
// Compute expected signature
const signaturePayload = `${timestamp}.${payload}`;
const expected = 'sha256=' + crypto
.createHmac('sha256', secret)
.update(signaturePayload)
.digest('hex');
// Constant-time comparison
return crypto.timingSafeEqual(
Buffer.from(expected),
Buffer.from(signature)
);
}
Python
import hmac
import hashlib
import time
def verify_webhook(request, secret):
timestamp = request.headers.get('X-Webhook-Timestamp')
signature = request.headers.get('X-Webhook-Signature')
payload = request.data.decode('utf-8')
# Check timestamp to prevent replay attacks
request_time = int(timestamp)
current_time = int(time.time())
if abs(current_time - request_time) > 300: # 5 minutes
return False
# Compute expected signature
signature_payload = f"{timestamp}.{payload}"
expected = "sha256=" + hmac.new(
secret.encode('utf-8'),
signature_payload.encode('utf-8'),
hashlib.sha256
).hexdigest()
# Constant-time comparison
return hmac.compare_digest(expected, signature)
Which events Somiti sends
The form lists 21 events in six groups. Most are sent as soon as the change is saved; six aren’t sent at the moment, so don’t build anything that waits for them.
Members
| Event | Sent when |
|---|---|
member.created |
A new account is made in your community: a sign-up, someone you add or import, or a guest registering for a public event |
member.updated |
Someone’s name, email, phone or role changes |
member.status_changed |
Someone’s account status changes (Active, Inactive, Suspended) |
member.deleted |
Not sent at the moment |
Memberships
| Event | Sent when |
|---|---|
membership.created |
A membership is created |
membership.activated |
A membership’s status changes to Active |
membership.paused |
A membership is paused |
membership.cancelled |
A membership is cancelled |
membership.expired |
Someone sets a membership’s status to Expired. It isn’t sent when a membership simply passes its end date. |
membership.renewed |
Not sent at the moment |
Events
| Event | Sent when |
|---|---|
event.created |
An event is created |
event.updated |
An event’s title, description, start or end time, venue name or capacity changes |
event.published |
An event’s status changes to Published (with the Publish button or the edit form) |
event.cancelled |
An event’s status changes to Cancelled (with Cancel Event or the edit form) |
Event registrations
| Event | Sent when |
|---|---|
event_registration.created |
Someone registers, including joining a waitlist |
event_registration.cancelled |
A registration is cancelled |
event_registration.attended |
Someone is checked in |
Payments
payment.completed, payment.failed and payment.refunded aren’t sent at the moment. To follow payments in another system, use Stripe’s own webhooks from your Stripe account.
Announcements
| Event | Sent when |
|---|---|
announcement.published |
An announcement is published |
What a message looks like
Every message has the same outside:
{
"id": "evt_9c4e2a7f1b3d5e8a0c6b2f4d",
"type": "member.created",
"created_at": "2026-10-30T15:12:00Z",
"data": {
}
}
| Field | Meaning |
|---|---|
id |
A unique id for this event: evt_ and 24 letters and numbers. It stays the same when Somiti retries, so use it to skip messages you’ve already handled. |
type |
The event name, like member.created |
created_at |
When the event happened (ISO 8601, UTC) |
data |
The details, which depend on the event (below) |
Ids in Somiti are text with a short prefix, like usr_ for people and evt_ for events, not numbers.
Member events
{
"id": "usr_7kq2mx",
"email": "[email protected]",
"name": "Jane Doe",
"status": "active",
"role": "member",
"phone": "(555) 010-2244",
"created_at": "2026-10-30T15:12:00Z",
"updated_at": "2026-10-30T15:12:00Z"
}
Membership events
{
"id": "mbr_4hc8wpzn",
"user_id": "usr_7kq2mx",
"tier_id": "tr_rcg2rvsd",
"tier_name": "Racing",
"status": "active",
"start_date": "2026-10-30",
"end_date": "2027-10-30",
"auto_renew": true,
"created_at": "2026-10-30T15:12:00Z",
"updated_at": "2026-10-30T15:20:00Z",
"user": {
"id": "usr_7kq2mx",
"email": "[email protected]",
"name": "Jane Doe"
}
}
Event events
{
"id": "evt_nightrd2",
"title": "Night Ride & Taco Social",
"description": "An easy 20-mile loop under the lights...",
"category": "Social",
"status": "published",
"start_datetime": "2026-11-07T22:00:00Z",
"end_datetime": "2026-11-08T01:00:00Z",
"location_type": "in_person",
"venue_name": "Foundry Taproom",
"max_capacity": 30,
"registration_count": 34,
"created_at": "2026-10-05T16:00:00Z",
"updated_at": "2026-10-05T16:01:00Z"
}
registration_count counts every registration for the event, including waitlisted and cancelled ones.
Event registration events
{
"id": "evr_6tn3ydkq",
"event_id": "evt_nightrd2",
"user_id": "usr_7kq2mx",
"status": "registered",
"payment_status": "paid",
"amount_paid_cents": 1250,
"registered_at": "2026-10-29T22:41:00Z",
"event": {
"id": "evt_nightrd2",
"title": "Night Ride & Taco Social"
},
"user": {
"id": "usr_7kq2mx",
"email": "[email protected]",
"name": "Jane Doe"
}
}
status is registered, waitlisted, attended or cancelled. Money is in cents: 1250 is $12.50.
Announcement events
{
"id": "ann_wntrrd26",
"title": "Winter riding schedule",
"content": "From November 1 the Sunday Club Ride starts at 9:30...",
"target_audience": "all_members",
"published_at": "2026-10-28T14:00:00Z",
"expires_at": null,
"created_at": "2026-10-28T12:00:00Z"
}
HTTP headers
Every message comes with these headers:
| Header | Meaning |
|---|---|
Content-Type |
application/json |
User-Agent |
Somiti-Webhooks/1.0 |
X-Webhook-Id |
The webhook’s id (wbh_...) |
X-Webhook-Event |
The event name, like member.created |
X-Webhook-Delivery |
The delivery’s id (wbd_...) |
X-Webhook-Timestamp |
When this attempt was sent, as a Unix timestamp |
X-Webhook-Signature |
sha256= and the signature (see Verify webhook signatures) |
Retries
Somiti sends each message a moment after the event, in the background. Your system has 30 seconds to accept the connection and 30 more to answer.
If it answers with anything other than 200 to 299, or doesn’t answer in time, Somiti tries again: three attempts in all, with a 30-minute wait before the second and the third. After the third failed attempt the delivery is marked Failed and Somiti gives up on it. There’s no button to resend a failed delivery, so plan for catching up another way, like a nightly export.
Tip: Answer with a 200 as soon as the message arrives, then do the slow work afterwards. If your system takes longer than 30 seconds, Somiti counts it as a failure and sends the same message again.
Troubleshooting
Nothing is arriving.
- Check the webhook’s status says Active.
- Check the events you need are under Subscribed Events, and that they’re ones Somiti sends (see Which events Somiti sends).
- Click Send Test and look at the newest row in Recent Deliveries.
Signatures don’t match.
- Check you’re using the current secret. If someone clicked Regenerate, the old one stopped working.
- Use the raw body exactly as it arrived. Parsing the JSON and turning it back into text can change the spacing or key order.
- Join the timestamp and the body with a
.between them.
Deliveries are failing.
- Look at Response in Recent Deliveries. A 500 means your system hit an error; a 401 or 403 means it refused the request; “does not resolve to a public address” means the address points somewhere Somiti won’t send to.
- Retrying means Somiti hasn’t given up yet. Check back in half an hour.
The same event arrived twice.
- A retry after a slow answer can bring the same message again. Keep the
idof each message you’ve handled and skip repeats.
Related docs
- Integrations for Slack and Mailchimp
- Slack integration for posting announcements and events to a channel
- Settings for the rest of your community’s settings