Webhooks v1 → v2
Webhooks v1 was the per-workspace Send Webhook (webhook:send) Action.
It has been retired and removed. Existing Send Webhook Actions were
deleted, nothing delivers v1 payloads any more, and an older archive, template,
Workflow or Journey that still contains one imports without it, reporting a
retired_action diagnostic.
Webhooks v2 is the replacement: organization webhooks, configured at Organization → Webhooks. An organization can run more than one endpoint, each with its own event types and workspace coverage. This page is the reference for rebuilding a v1 integration on v2.
The short version
| Webhooks v1 (retired) | Webhooks v2 | |
|---|---|---|
| Configured in | Each workspace, as an Action | Organization → Webhooks |
| Number of things to manage | One rule per event per binding | One endpoint per receiver, each with its own events and coverage |
| New workspace joins | Needed its own rules | Covered automatically, or by workspace label |
| Vocabulary | Event Rule triggers | The activity event catalog |
| Payload | Five shapes by family, included field values | One shape, identifiers only |
| Per-Form / per-Workflow targeting | Yes: a rule bound to one object | No: you filter on your side |
| Data record events | Yes | Yes: emitted, gated on the per-Form opt-in |
| Retries | 5 attempts, 4xx permanent | 12 attempts over about a day, 4xx retried |
| Backlog while your receiver is down | Lost after the retries | Held for 7 days, delivered on resume |
| Test send | Per rule, in the action form | Per endpoint, with an editable payload |
What does not map across
Two v1 behaviours have no v2 equivalent. Plan your receiver around them:
- Field values in the payload. v2 delivers identifiers and field slugs; your receiver reads the values back over the API. See Reading a field value.
- Firing for one specific Form, Workflow or Journey. v2 delivers every occurrence of a subscribed type, and your handler drops the ones it does not want. See There is no per-object filtering in v2.
The two differences in detail
There is no per-object filtering in v2
A v1 rule was bound to one object: this Form, this Workflow, this Journey. Only that object's events fired it.
v2 has no equivalent. An endpoint subscribed to an event type receives every
occurrence of that type, from every workspace it covers, and you drop the ones
you do not want in your handler. The identifiers you need to make that decision
are in the payload — workspace_uuid, subject, and the ref fields inside
detail.
This is a real trade, and mostly a good one: instead of N rules to keep in step
across M workspaces, you configure an endpoint once and add one if in code you
already control. The cost is that events you do not care about cross the wire.
Server-side per-endpoint filtering (on Form id, say) is a reasonable thing to add later. If your integration needs it, say so — it is a feature request, not a limitation of the design.
Data record events
v1's data_record:created, data_record:updated and data_record:changed were
the usual foundation of a "sync this Form's submissions to our system"
integration.
v2 emits data_record.created and data_record.updated for a Form that has
opted in, carrying the data_type reference and the slugs of the fields that
changed — never their values. What to know before you move onto them:
- Emission is opt-in, per Form, and off by default. Turn on
webhook_events_enabledon the Form; until you do, an endpoint subscribing to these receives nothing from it. Records written through the REST API (including Site Forms), the AI tools, CSV/import, and signup emit. - Connector syncs emit too, for these writes: Monday record boards (both
the scheduled poll and Monday's own webhook), eCW and athenahealth patient
profile and Condition records, and new eCW care-plan items. An event is sent
only after the sync's write has been saved, with
actor.kind: "system"anddetail.source_channel: "sync"; the vendor is not named. These sync events publish the webhook event only and run no Action (EventRule): if you rebuild adata_record:*Action of another kind, it does not fire on connector writes. An unchanged re-sync sends nothing, and a re-link that only changes the record's external ID sends nothing either. Inbound record sources (form submissions, booking-link meetings, deals) and Monday Member-board Form fields already emitted and still do, once per write. Directories (shared lookup lists such as CRM owners), connector-managed Member fields and eCW care-plan item updates emit no record event; those writes never randata_record:*rules on v1 either. - Delivery is best effort at the moment of the write. The event is recorded right after the record is saved; if the process stops in that instant, the event for that write can be lost (the record itself is not). Once recorded, v2's normal retries and seven-day backlog apply.
- It replaces
:createdand:updated, not:changed. v1's:changedwas a catch-all; subscribing to both v2 types is the closest equivalent. - There is no per-Form targeting — as with every v2 event, you filter on
dataTypeon your side. See There is no per-object filtering in v2.
member.attributes_changed remains the type to use when what you care about is
the Member's own record rather than a standalone Form submission: it carries the
data_type reference and changed field slugs for the member attributes.
Mapping the vocabulary
Only some v1 triggers have a v2 counterpart, and the counterpart is often coarser, because v2 records occurrences rather than rule firings. The table describes v1 as it behaved before its removal.
| v1 trigger | v2 event type | Notes |
|---|---|---|
data_record:created | data_record.created | Emitted for a Form whose per-DataType opt-in is on, including the connector syncs listed above (as system, channel sync). Directories and connector-managed Member fields emit in neither version |
data_record:updated | data_record.updated | Emitted for a Form whose per-DataType opt-in is on, including the connector syncs listed above. Directories, connector-managed Member fields and eCW care-plan item updates emit in neither version |
data_record:changed | data_record.created + data_record.updated | v1's catch-all has no single counterpart |
member:updated | member.attributes_changed | Field slugs only, no values |
workspace:member_joined | member.created | The v1 trigger never fired; v2's does |
workspace:member_left | member.removed | The v1 trigger never fired; v2's does. Carries a removal reason |
chat:created | chat.started | Manager and agent-job chats do not deliver chat.started; their confirmed sends to a Member can deliver message.sent |
chat:summary | chat.summary | Signal only: names the Chat and channel, never the summary text |
workflow:execute | assignment.started | v2 names the Member's run, not the step |
task:execute | assignment.task_entered | Fires when the Assignment enters a Task, for every Task type. detail.task names the Task; detail.task_lineage_uuid stays the same across Workflow publishes, so match on it. Filter on detail.workflow and the lineage on your side |
workflow:user_message | member.message_received | Subject is the Member who wrote the message. Fires for every Member message on a workspace Chat — every channel, whether or not the Agent replied. v1 fired on Workflow Chats only: filter on detail.workflow. No message text; a CEL condition on Member labels becomes a read of the subject Member on your side |
message:created (inbound) | member.message_received | Manager and agent-job Chats never deliver this inbound event. For outbound messages, message.sent records confirmed SMS, WhatsApp, email and spoken voice sends; persisting an assistant message alone does not emit it |
journey:enrolled | journey.enrolled | Subject is the member, not the journey |
journey:completed | journey.completed | Subject is the member |
journey_step:execute | journey.step_transitioned | Carries from/to status |
call:started | call.started | |
call:completed | call.completed + call.missed | v1 fired call:completed for every disposition; v2 splits every ending that never connected (no answer, timeout, rejected, went to voicemail, …) out as call.missed. Subscribe to both |
call:summary | call.summary | Phone channels only; signal only, never the summary text — read it from the Chat named in detail.chat |
calendar_event:* | — | No v2 calendar events |
routine:triggered | routine.started | v2 also has routine.completed / routine.failed |
voicemail:received | voicemail.transcribed | Fires at the same moment v1 did — once transcription resolved (and also for a voicemail with no linked member, which v1 skipped), with detail.outcome saying whether it succeeded. Not voicemail.received, which fires when the caller is sent to voicemail, before there is anything to read. No transcript in the payload |
fax:received | — | No v2 fax events |
connector:event | — | |
link:clicked | — | No v2 click event. To rebuild the click → webhook shape, create a link:clicked Action that runs Label Member (member:label) and subscribe the endpoint to member.labels_changed; detail.added / detail.removed carry the label refs, so match on the label's uuid |
The v2 event catalog is the authoritative list, generated from the vocabulary itself.
Worked example: many per-Form rules for one data type
The shape this comes up in: an integration partner needed one workspace's
Intake Form kept in sync with their system, so they created a Send Webhook
Action per event, each bound to that Form — data_record:created,
data_record:updated, plus a few member events — and then repeated the set for
every workspace that came online. Those Actions have now been deleted. To
rebuild the integration:
-
List what the receiver used to get. The v1 Actions no longer exist in Gravity Rail, so work from your side: each v1 delivery carried
event(the trigger) andeventRule(the rule's name and id). Note each trigger and the object it was bound to. -
Map each trigger with the table above. For
data_record:*, turn on the Form's opt-in (webhook_events_enabled). Its rows then emit when written through the REST API (including Site Forms), AI tools, CSV/import, signup, or one of the connector syncs that emit (Monday record boards, eCW / athenahealth patient profiles and Conditions, new eCW care-plan items). A Form written only by a Directory refresh, connector-managed Member fields or eCW care-plan item updates has no record event; usemember.attributes_changedwhere a Member field is what changed. -
Create one v2 endpoint at Organization → Webhooks. Leave the workspace list and label selector empty so it covers every workspace including future ones (or select a label such as
production) — that is the part that removes the per-workspace work. Subscribe it to the v2 types from step 2. -
Add the filter you used to get from the binding. Where a v1 rule was bound to the
IntakeForm, your handler now checks the payload instead. Fordata_record.*the Form isdetail.data_type.uuid; formember.attributes_changedit is alsodetail.data_type.uuid; for other types it is whichever ref names the object. Ignore what does not match. -
Test before you rely on it. Press Send test event on the endpoint, pick a type, and edit the sample payload so the ids are ones your handler will resolve. Nothing is queued and nothing is retried, so you can do this as many times as you need. A 2xx shows the request reached your receiver; it does not prove your handler acted on the payload or verified the signature. Check your handler's logs, and see Testing for how to confirm both.
-
Watch real traffic. The endpoint's Deliveries tab shows each delivery, its attempts and the latest response.
Net result for that partner: the endpoint they created covers new workspaces automatically, replacing a set of rules per workspace.
Things to change in your handler
- Verify against the raw body. Keys arrive alphabetically sorted and the signature covers the exact bytes. The header and scheme are unchanged from v1; see Request signing.
- Dedupe on
dedupe_key. v2 is at-least-once; the samededupe_keyarrives on every retry and replay of one occurrence, and every occurrence has its own — eachdata_record.updatedon one record carries a different one. Pairing it withoccurred_atis harmless, and covers the one exception for events recorded before this guarantee shipped (see Delivery). It replaces v1'seventId. - Return
2xxfast. v2 retries4xxas well as5xx, so "reject it and it goes away" is not true here. Accept, then process asynchronously. - Ignore unknown enum values. Every vocabulary in a v2 payload is closed but
growing. An unrecognised
event_type,subject.kindordetailenum member means "a new member exists", not "something is wrong". - Re-read for detail. v2 delivers identifiers. Where a v1 payload handed you
member.emailordataRecord.fields, v2 hands you a uuid and you fetch. - Handle
"test": true. A test send sets it at the top level of the body. Discard or route those however you like — it is inside the signed body, so you can trust it.
Related
- Webhooks — overview, and inbound Routine webhooks
- Webhooks v2 — the organization system and its event catalog
- Self-serve integration kit — screens, commands and APIs for deliveries