Zapier automation integration
The Zapier integration exposes WorldMonitor intelligence as searchable data and event-driven automation. It lets a user connect an API plan key, find current risk and conflict information, and start Zaps from trusted news, market, hazard, maritime, and country-risk signals. The integration calls the public WorldMonitor API and does not depend on the web client. It is the automation child of Desktop and external clients, alongside the Tauri desktop application, browser plugin country intelligence, and CLI terminal dashboard. integrations/…/README.md• L1-7
Integration boundary
The Zapier app is an external client of the WorldMonitor REST API. Zapier owns the workflow and field mapping, while WorldMonitor owns API access, event rules, subscription state, and delivery of signal data. This makes the app a consumer of shared WorldMonitor contracts rather than a second intelligence system. integrations/…/index.js• L19-42
The main request and event path is:
flowchart LR
User[Zapier user] --> Key[API plan key]
Key --> App[WorldMonitor Zapier app]
App --> API[WorldMonitor REST API]
API --> Search[Search results]
API --> Hook[Webhook subscription]
Signals[WorldMonitor signals] --> Hook
Hook --> Zap[Zap workflow]
Account connection
API key authentication
The connection uses a WorldMonitor API key from an API Starter or API Business plan. The connection test calls a real country-risk endpoint, so a successful result confirms both that the key is accepted and that the account can use the API surface. integrations/…/authentication.js• L5-25
The app sends the key through the X-WorldMonitor-Key header. It does not use a public health endpoint as a validity check because that endpoint does not prove that the key works. integrations/…/constants.js• L3-5, integrations/…/README.md• L55-59
References: integrations/…/authentication.js• L5-25 integrations/…/constants.js• L3-5 integrations/…/README.md• L55-59
Request middleware
Request middleware applies the saved key and a stable WorldMonitor user agent to every API call. Response middleware turns API failures into Zapier errors that preserve expired-auth status, forbidden access, general HTTP status, and field-level validation messages. This lets a user fix a bad key or input from the Zap editor instead of seeing an opaque request failure. integrations/…/middleware.js• L5-47
References: integrations/…/middleware.js• L5-47 integrations/…/authentication.test.js• L17-65
Event trigger registry
Shared event contract
The event registry is the shared description of push events. It defines the event name, user filters, payload shape, delivery identity, limits, and threshold or occurrence meaning. The same contract is mirrored into the Zapier bundle so the app can present matching inputs and output fields while the server and delivery worker use the canonical definition. shared/event-triggers.json• L1-29, integrations/…/constants.js• L22-29
The registry currently exposes these instant signal families to Zapier:
| Signal | User value |
|---|---|
news.breaking | Breaking headlines filtered by importance, severity, topic, and country |
market.move | Large moves in tracked equities, commodities, or crypto assets |
natural.hazard | New earthquakes, storms, fires, floods, volcanic events, and related hazards |
chokepoint.disruption | Maritime chokepoint disruption above a chosen alert and live-signal level |
country.risk_surge | A sharp rise in a monitored country’s instability score |
References: shared/event-triggers.json• L30-36 shared/event-triggers.json• L139-145 shared/event-triggers.json• L242-247 shared/event-triggers.json• L357-362 shared/event-triggers.json• L450-456 integrations/…/index.js• L33-42
Threshold and occurrence events
Threshold events represent a condition that crosses a boundary. Chokepoint disruption and country-risk surge use this model, with re-arm rules and cooldowns to avoid repeated alerts while a condition remains high. Occurrence events represent a new story, market move, or hazard. They use event identity and deduplication so repeated source observations do not become an unbounded stream of new alerts. shared/event-triggers.json• L25-28, shared/event-triggers.json• L77-92, shared/event-triggers.json• L181-190
Each trigger lets the user narrow the signal before WorldMonitor sends it. News uses headline and classifier filters, markets use asset and direction filters, and hazards use type, magnitude, alert level, and country filters. The server validates these filters against the registry contract. shared/event-triggers.json• L258-301, shared/event-triggers.json• L369-397, shared/event-triggers.json• L462-497
References: shared/event-triggers.json• L25-28 shared/event-triggers.json• L77-92 shared/event-triggers.json• L181-190 shared/event-triggers.json• L258-301 shared/event-triggers.json• L369-397 shared/event-triggers.json• L462-497
Search and polling access
Search actions
Search actions give a Zap a current answer without waiting for a new event. They cover country risk, chokepoint status, recent conflict events, keyword news, and a strategic risk overview. Results are shaped into stable rows so later Zap steps can map risk scores, locations, headlines, and source data. integrations/…/index.js• L26-32
The news search reads a selected digest and applies its keyword and category match in the app. The strategic overview combines the global risk roll-up with the highest country scores. Conflict search returns the newest 25 events for a country, while the country and chokepoint searches return the selected live record. integrations/…/find-news.js• L11-40, integrations/…/strategic-risk-overview.js• L9-45, integrations/…/latest-events.js• L5-13, integrations/…/country-risk.js• L5-17, integrations/…/chokepoint-status.js• L5-12
References: integrations/…/find-news.js• L11-40 integrations/…/strategic-risk-overview.js• L9-45 integrations/…/latest-events.js• L5-13 integrations/…/country-risk.js• L5-17 integrations/…/chokepoint-status.js• L5-12
Polling and editor data
Disease outbreaks use polling because the source is a time-ordered report list rather than a signed shipping webhook. The integration also provides hidden country and chokepoint lists for dynamic Zap fields. Hook triggers use current API records as editor samples, shaped like real deliveries so field mapping remains useful before the first live signal arrives. integrations/…/new-disease-outbreak.js• L5-24, integrations/…/country-list.js• L5-27, integrations/…/chokepoint-list.js• L5-24, integrations/…/chokepoint-disruption.js• L42-75
References: integrations/…/new-disease-outbreak.js• L5-24 integrations/…/country-list.js• L5-27 integrations/…/chokepoint-list.js• L5-24 integrations/…/chokepoint-disruption.js• L42-75
Signed webhook behavior
Subscription lifecycle
An instant trigger registers the Zap’s target URL as a WorldMonitor webhook subscription. WorldMonitor returns a subscriber id and a signing secret once; Zapier stores both for later unsubscribe and delivery checks. The integration reports an expiration date before the server’s 30-day lifetime so Zapier can renew the subscription in time. integrations/…/hooks.js• L14-43, integrations/…/constants.js• L27-29
When a Zap is removed, the app deletes the stored subscription. A missing subscription is treated as already removed, which keeps Zapier cleanup safe when the server has already discarded the record. integrations/…/hooks.js• L45-59
References: integrations/…/hooks.js• L14-59 integrations/…/constants.js• L27-29
Delivery trust
Every accepted delivery must carry the version-two signature, timestamp, event name, and delivery id. The signature binds those values to the exact request body with the subscription secret. The timestamp must be within five minutes, and malformed or changed values fail before the Zap receives a row. The older body-only signature is not a fallback because it cannot stop a captured request from being replayed with different delivery metadata. integrations/…/hooks.js• L80-149, shared/event-triggers.json• L12-23
WorldMonitor keeps the same delivery id when it retries a failed event. Zapier uses that id as the row id, but Zapier does not deduplicate REST-hook runs itself. A downstream workflow that must be idempotent should use the delivery id when it records or acts on an alert. integrations/…/hooks.js• L101-149
The delivery path is:
sequenceDiagram
participant WM as WorldMonitor
participant Zap as Zapier trigger
participant Flow as Zap workflow
WM->>Zap: POST event + V2 headers
Zap->>Zap: Check secret, body, event, id, timestamp
alt valid and fresh
Zap->>Flow: Return one row keyed by delivery id
else invalid or stale
Zap-->>WM: Reject delivery
end
References: integrations/…/hooks.js• L80-149 shared/event-triggers.json• L12-23 integrations/…/signature-v2.test.js• L54-121
Test coverage
Contract and schema checks
The test suite checks that the mirrored registry stays byte-for-byte equal to the canonical registry. It also checks that each registry event has a matching REST-hook trigger, that samples contain required payload fields, and that user inputs and output fields stay aligned with the registry. Zapier’s compiled app schema must also validate without errors. integrations/…/event-registry.test.js• L12-76, integrations/…/schema.test.js• L8-13
References: integrations/…/event-registry.test.js• L12-76 integrations/…/schema.test.js• L8-13
Authentication and signature checks
Authentication tests cover a valid key, an expired or invalid key, and field-level API errors. Signature tests cover valid deliveries, altered metadata or bodies, stale timestamps, missing secrets, malformed headers, and legacy-only requests. Together they protect the two contracts that can silently break an automation: access to the API and trust in an inbound event. integrations/…/authentication.test.js• L17-65, integrations/…/signature-v2.test.js• L54-145
References: integrations/…/authentication.test.js• L17-65 integrations/…/signature-v2.test.js• L54-145
Change checklist
When these files or sections are changed, remember to consider these:
- Update integrations/…/event-triggers.json with shared/event-triggers.json when the canonical event registry changes. The registry test requires an exact copy.
- Keep each registry event’s Zapier input fields, defaults, choices, required output fields, and sample row aligned with its
inputSchemaandpayloadSchema. - Coordinate any signature-header or delivery-id change with both webhook senders and the Zapier receiver. Version two is required and has no legacy fallback.
- Preserve the 29-day renewal signal when the server’s 30-day subscription lifetime changes.
- Keep dynamic country and chokepoint lists aligned with the values the server accepts for webhook registration.
- Keep sample rows shaped like live delivery rows so Zap field mapping does not change between setup and execution.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Canonical registry changes without updating the Zapier mirror | The app can expose stale event filters or payload fields | Byte-for-byte registry test |
| API key is expired, lacks API access, or is sent under the wrong header | Connection or later Zap steps fail as auth or forbidden errors | Real country-risk connection test and request middleware |
| V2 signature, event, delivery id, body, or timestamp is changed | The event is rejected and the Zap does not run | HMAC verification, strict header checks, and five-minute freshness window |
| A retried delivery is treated as a new action by a downstream Zap | An external action can run more than once | Use the stable delivery id for downstream deduplication |
| A webhook subscription reaches its TTL before renewal | WorldMonitor stops sending events to that Zap | Expiration is reported before the 30-day server lifetime |
| A trigger input is not accepted by the registry schema | Subscription registration returns a validation error | Registry-driven fields and server-side scope validation |
Key files
| File | Why to read it |
|---|---|
| integrations/…/index.js | Shows the complete Zapier surface: authentication, middleware, searches, and triggers. |
| integrations/…/authentication.js | Defines the user connection and the API-key validity check. |
| integrations/…/middleware.js | Defines shared request headers and API error behavior. |
| shared/event-triggers.json | Defines the shared event, filter, payload, delivery, and retry contract. |
| integrations/…/hooks.js | Connects Zapier subscriptions to WorldMonitor webhooks and verifies signed deliveries. |
integrations/zapier/triggers/ | Shows how the five registered signal families become instant Zapier triggers. |
integrations/zapier/searches/ | Shows the current lookup actions available to downstream workflows. |
| integrations/…/event-registry.test.js | Protects alignment between the canonical registry and the Zapier app. |
| integrations/…/signature-v2.test.js | Protects the signed-delivery and replay-resistance contract. |
| integrations/…/authentication.test.js | Protects API connection and error behavior. |