Skip to main content

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

  1. Click Add Webhook (on the Webhooks page, or in the Custom Webhooks box on the Integrations page).
  2. 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.
  3. 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.
  4. Leave Status on Active.
  5. 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.

A webhook's page: the Configuration card with the endpoint URL, the signing secret hidden as dots with Reveal and Regenerate, an Active status and four subscribed events, and the Statistics card with total deliveries, a success rate bar, the successful and failed counts and when it last fired.
  1. The signing secret your system uses to check messages came from Somiti.
  2. The events this webhook sends.
  3. 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:

The Recent Deliveries table for a webhook: six rows, each with the event name and its id, a Delivered or Failed status, the response code, how long the response took and the time it was sent. One member.created delivery failed with a 503.
  1. Failed means all three attempts were refused.
  2. 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:

  1. Extract the X-Webhook-Timestamp and X-Webhook-Signature headers.
  2. Get the raw request body (the JSON payload).
  3. Concatenate: timestamp + "." + payload.
  4. Compute HMAC-SHA256 using your webhook secret.
  5. Compare with the provided signature using constant-time comparison.
  6. 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 id of each message you’ve handled and skip repeats.