Webhooks

Webhooks let Gomry notify your own systems the moment something happens in your organization: someone registers, a subscription changes, or a form is submitted. Instead of polling the API, you register one or more HTTPS URLs and Gomry sends an HTTP POST request with a JSON payload to each of them as events occur. There are two ways to receive them:

	Webhook subscriptions	Organization webhook URLs
Set up with	The API (`POST /webhooks`), or Zapier	The dashboard
Events	Pick one event type per subscription, optionally one event or form	Every event goes to every URL
Payload	Versioned envelope with an event `id` and the object in its API shape	Legacy shape (below)
Signed	Yes, HMAC-SHA256	No
Retries	Yes, with backoff	No

Use webhook subscriptions for anything new. Organization webhook URLs keep working for existing setups.

Webhook subscriptions

Subscribe one HTTPS URL to one event type with Create Webhook Subscription, and remove it with Delete Webhook Subscription. The key needs the read scope of the data the event carries. This is the mechanism Gomry’s Zapier app uses for its instant triggers, so a Zap you turn on appears in List Webhook Subscriptions.

curl -X POST "https://www.gomry.com/api/v1/webhooks" \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/webhooks/gomry", "event": "attendee.registered" }'

The response includes a secret (whsec_...). It is shown once: store it to verify signatures.

Event types

`event`	When it fires	Needs	Optional filter
`attendee.registered`	Someone registers or buys tickets through checkout, free or paid, web or app. One delivery per ticket. Includes tickets waiting for approval (`status: "pending_approval"`). Guests you add yourself and RSVPs (“maybe”, “not going”) do not fire it.	`attendees:read`	`event_id`
`form_response.created`	A form or application is submitted. Drafts do not fire it.	`applications:read`	`form_id`
`form_response.updated`	A form response changes after it was submitted, for example you accept or reject it.	`applications:read`	`form_id`

Envelope

Every delivery is a POST with a JSON body:

{
  "id": "evt_5c1f0e2a9b8d7c6e5f4a3b2c1d0e9f8a",
  "type": "attendee.registered",
  "created_at": "2026-10-15T10:00:00.000Z",
  "organization_id": "oWao7AbCdEfGhIjKlMnO",
  "data": { "...": "the object, see below" }
}

Field	Description
`id`	Unique per event and stable across retries. Deduplicate on it.
`type`	The event type.
`created_at`	When the event happened.
`organization_id`	Your organization.
`data`	The object as it was when the event happened, in the same shape the REST API returns, plus the extras listed below.

Headers: Gomry-Signature, Gomry-Event-Id, Gomry-Event-Type, Gomry-Webhook-Id (the subscription) and User-Agent: Gomry-Webhooks/1.0.

Event payloads

attendee.registered: the attendee plus event_id, contact_id, payment_id, phone_number, the registration answers (answers as a list and answers_by_question keyed by question), a summary of the event and the full contact.

{
  "id": "Xy12AbCdEfGhIjKlMnOp",
  "status": "valid",
  "ticket_class_id": "Tc12AbCdEfGhIjKlMnOp",
  "ticket_class_name": "General Admission",
  "barcode": "GMRY-8F3K2",
  "first_name": "Jordan",
  "last_name": "Rivera",
  "email": "jordan@example.com",
  "phone_number": "+15551234567",
  "checked_in_at": null,
  "utm_source": "instagram",
  "utm_medium": null,
  "utm_campaign": null,
  "utm_content": null,
  "utm_term": null,
  "created_at": "2026-10-15T10:00:00.000Z",
  "updated_at": "2026-10-15T10:00:00.000Z",
  "event_id": "AbCdEfGhIjKlMnOpQrSt",
  "contact_id": "Ct12AbCdEfGhIjKlMnOp",
  "payment_id": "Py12AbCdEfGhIjKlMnOp",
  "answers": [{ "question": "Dietary restrictions", "answer": "Vegetarian" }],
  "answers_by_question": { "Dietary restrictions": "Vegetarian" },
  "event": {
    "id": "AbCdEfGhIjKlMnOpQrSt",
    "name": "Summer Rooftop Party",
    "start": { "utc": "2026-08-01T18:00:00.000Z", "timezone": "Europe/Rome" },
    "end": { "utc": "2026-08-01T23:00:00.000Z", "timezone": "Europe/Rome" },
    "url": "https://www.gomry.com/event/summer-rooftop-party-AbCdEfGhIjKlMnOpQrSt"
  },
  "contact": { "id": "Ct12AbCdEfGhIjKlMnOp", "email": "jordan@example.com", "...": "see Get Contact" }
}

form_response.created and form_response.updated: the application (with applicant), plus answers_by_question and the form (id, name). To see real payloads from your own data, call List Webhook Samples.

Verifying signatures

Gomry-Signature looks like t=1792056000,v1=5257a869.... v1 is the hex HMAC-SHA256 of {t}.{raw body}, keyed with the subscription’s secret. Compute it over the raw request bytes (before any JSON parsing), compare in constant time, and reject timestamps more than 5 minutes old.

import crypto from "node:crypto";

export function verifyGomrySignature(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const received = Buffer.from(parts.v1 ?? "", "hex");
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

import hashlib, hmac, time

def verify_gomry_signature(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = int(parts.get("t", "0"))
    if abs(time.time() - t) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Delivery and retries

Answer with any 2xx within 10 seconds. Do slow work after responding.
A timeout, a network error, 429 or 5xx is retried with backoff (up to 3 more attempts). Other 4xx answers are not retried.
Answering 410 Gone deletes the subscription. Zapier does this when a Zap is deleted.
Redirects are not followed.
An event can arrive more than once, and events can arrive out of order. Deduplicate on the envelope id.
Revoking the API key that created a subscription stops its deliveries. Removing the read scope from the key pauses them until the scope is back.
An organization can have up to 100 active subscriptions.

Zapier

Gomry’s Zapier app connects with an organization API key and uses these subscriptions for its instant triggers (New Attendee, New Form Response, Updated Form Response). You don’t need to call this API yourself to use it.

Organization webhook URLs

Configuring webhook URLs

Webhook endpoints are configured per organization.

Open your API key settings

Go to Organization Settings, API Keys in your Gomry dashboard and scroll to Webhooks.

Add your endpoint URLs

Enter one or more endpoint URLs, one per line. Every URL you add receives a copy of every webhook event for your organization.

Save

Save your settings. New events will start being delivered to your endpoints.

Use an https:// endpoint that is publicly reachable and responds quickly (see Delivery & reliability). Webhooks are scoped to the whole organization — there is currently no per-event subscription.

How delivery works

Each event is sent as a separate HTTP request to every configured URL:

Property	Value
Method	`POST`
Content-Type	`application/json`
Body	A single JSON event object (see Payload)
Timeout	5 seconds
Retries	None — delivery is best-effort

Your endpoint should respond with a 2xx status code as quickly as possible. Do any heavy processing after acknowledging the request (for example, by pushing the payload onto a queue), so you don’t hit the delivery timeout.

Webhook payloads are not currently signed, and there is no shared secret or signature header on this delivery path. Treat the data as advisory: keep your endpoint URL private, accept requests only over HTTPS, and confirm anything sensitive (such as payment amounts) against the Payments API using the payment.id from the payload before acting on it.

Legacy event types

The type field identifies what happened. The most common event is payment.succeeded, which fires when an attendee buys a ticket.

`type`	When it fires
`payment.succeeded`	A one-time payment completes — most commonly a ticket purchase. `payment.billing_reason` is `one_time_payment`.
`subscription.created`	A recurring subscription is created. `payment.billing_reason` is `subscription_create`.
`subscription.deleted`	A subscription is cancelled or ends.
`form_response.created`	A form / application is submitted for the first time.
`form_response.updated`	An existing form / application response is updated (e.g. status change).

Form-response payloads on this path do not carry a type field, but always include formID and applicationID. Use the presence of those fields to identify a form-response event. Webhook subscriptions always set type.

Payload structure

All events share one envelope. Fields are populated based on the event type, so most are optional — always guard for missing values.

Field	Type	Description
`type`	string	The event type (see table above).
`spaceID`	string	The space the event belongs to, when applicable.
`organizationID`	string	The organization the event belongs to.
`date`	string (ISO 8601)	When the event occurred.
`user`	object	The person who triggered the event (see below).
`payment`	object	Payment details — present on `payment.` and `subscription.` events.
`subscription`	object	Subscription details — present on `subscription.*` events.
`lineItems`	array	Line items for the payment. Ticket line items have `type: "ticket"`.
`formID`	string	The form ID — present on `form_response.*` events.
`applicationID`	string	The application/response ID — present on `form_response.*` events.
`submission_answers`	object	Submitted answers keyed by question — present on `form_response.*` events.
`responseStatus`	string	`Pending`, `Accepted`, `Rejected`, `Draft`, or `Deleted` — form responses.
`isNewApplication`	boolean	Whether this is the first submission — form responses.

`user` object

Field	Type	Description
`id`	string	The user’s ID.
`contactID`	string	The contact record ID in your organization.
`name`	string	Full name.
`firstName` / `lastName`	string	Name parts (populated on form-response events).
`email`	string	Email address.
`phoneNumber`	string	Phone number.
`linkedin`, `instagram`, `github`, `twitter`, `website`	string	Social / web profiles, when provided.
`bio`	string	Short biography, when provided.
`location`	string \| object	Location, when provided.
`country`	string	Country, when provided.

`payment` object

Field	Type	Description
`id`	string	The payment ID. Use this to look up the payment via the API.
`grossAmount`	number	Total amount charged, in the smallest currency unit.
`netAmount`	number	Amount after fees, in the smallest currency unit.
`currency`	string	ISO 4217 currency code (e.g. `usd`).
`productID`	string	The product ID.
`priceID`	string	The price ID.
`billing_reason`	string	`one_time_payment`, `subscription_create`, or `subscription_cycle`.

Example: ticket purchase

When an attendee buys a ticket, your endpoint receives a payment.succeeded event:

{
  "type": "payment.succeeded",
  "spaceID": "AbCdEfGhIjKlMnOpQrSt",
  "user": {
    "id": "user_123",
    "contactID": "contact_456",
    "name": "Jordan Rivera",
    "email": "jordan@example.com",
    "phoneNumber": "+15551234567",
    "linkedin": "https://linkedin.com/in/jordanrivera",
    "country": "US"
  },
  "date": "2026-06-11T18:30:00.000Z",
  "payment": {
    "id": "pay_789",
    "grossAmount": 5000,
    "netAmount": 4650,
    "currency": "usd",
    "productID": "prod_abc",
    "priceID": "price_def",
    "billing_reason": "one_time_payment"
  },
  "lineItems": [
    {
      "type": "ticket",
      "ticket_owner_email": "jordan@example.com",
      "quantity": 1
    }
  ]
}

Example: form submission

{
  "type": "form_response.created",
  "formID": "form_123",
  "applicationID": "app_456",
  "user": {
    "id": "user_123",
    "contactID": "contact_456",
    "name": "Jordan Rivera",
    "firstName": "Jordan",
    "lastName": "Rivera",
    "email": "jordan@example.com"
  },
  "submission_answers": {
    "What's your company?": "Acme Inc.",
    "Dietary restrictions": "Vegetarian"
  },
  "responseStatus": "Pending",
  "isNewApplication": true,
  "date": "2026-06-11T18:30:00.000Z"
}

Handling webhooks

import express from "express";

const app = express();
app.use(express.json());

app.post("/webhooks/gomry", (req, res) => {
  const event = req.body;

  // Acknowledge immediately, then process asynchronously.
  res.status(200).send("ok");

  switch (event.type) {
    case "payment.succeeded":
      // A ticket was purchased — event.payment.id, event.user.email, …
      handleTicketPurchase(event);
      break;
    case "form_response.created":
    case "form_response.updated":
      handleFormResponse(event);
      break;
    default:
      // form-response events may arrive without a `type`
      if (event.formID) handleFormResponse(event);
  }
});

app.listen(3000);

from flask import Flask, request

app = Flask(__name__)

@app.post("/webhooks/gomry")
def gomry_webhook():
    event = request.get_json()
    event_type = event.get("type")

    if event_type == "payment.succeeded":
        # A ticket was purchased
        handle_ticket_purchase(event)
    elif event_type in ("form_response.created", "form_response.updated") or event.get("formID"):
        handle_form_response(event)

    # Acknowledge quickly; process heavy work out of band.
    return "ok", 200

Best practices

Respond fast, process later

Return a 2xx within the 5-second timeout. Offload anything slow (emails, database writes, third-party calls) to a background job or queue.

Make your handler idempotent

Because there are no delivery guarantees and multiple endpoints can be configured, design your handler so processing the same event twice is safe — key off payment.id or applicationID.

Verify sensitive data against the API

Payloads are unsigned. Before acting on money-related data, re-fetch it from the Payments API using the payment.id from the payload.

Guard for missing fields

Most fields are optional and vary by event type. Always check for existence before reading nested values.

Getting Started

MCP Server

Agentic Commerce

Webhooks

Webhooks

Webhooks

Webhook subscriptions

Event types

Envelope

Event payloads

Verifying signatures

Delivery and retries

Zapier

Organization webhook URLs

Configuring webhook URLs

How delivery works

Legacy event types

Payload structure

`user` object

`payment` object

Example: ticket purchase

Example: form submission

Handling webhooks

Best practices

​Webhooks

​Webhook subscriptions

​Event types

​Envelope

​Event payloads

​Verifying signatures

​Delivery and retries

​Zapier

​Organization webhook URLs

​Configuring webhook URLs

​How delivery works

​Legacy event types

​Payload structure

​user object

​payment object

​Example: ticket purchase

​Example: form submission

​Handling webhooks

​Best practices

Webhooks

Webhook subscriptions

Event types

Envelope

Event payloads

Verifying signatures

Delivery and retries

Zapier

Organization webhook URLs

Configuring webhook URLs

How delivery works

Legacy event types

Payload structure

`user` object

`payment` object

Example: ticket purchase

Example: form submission

Handling webhooks

Best practices