Introducing a new way to review your PRs.

Read the announcement

koala73 / worldmonitor

Real-time global intelligence dashboard. AI-powered news aggregation, geopolitical monitoring, and infrastructure tracking in a unified situational awareness interface

View on GitHub

29 documents · Updated Nov 20, 2026

docs / zapier-automation-integration

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:

SignalUser value
news.breakingBreaking headlines filtered by importance, severity, topic, and country
market.moveLarge moves in tracked equities, commodities, or crypto assets
natural.hazardNew earthquakes, storms, fires, floods, volcanic events, and related hazards
chokepoint.disruptionMaritime chokepoint disruption above a chosen alert and live-signal level
country.risk_surgeA 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 inputSchema and payloadSchema.
  • 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

TriggerConsequenceGuard
Canonical registry changes without updating the Zapier mirrorThe app can expose stale event filters or payload fieldsByte-for-byte registry test
API key is expired, lacks API access, or is sent under the wrong headerConnection or later Zap steps fail as auth or forbidden errorsReal country-risk connection test and request middleware
V2 signature, event, delivery id, body, or timestamp is changedThe event is rejected and the Zap does not runHMAC verification, strict header checks, and five-minute freshness window
A retried delivery is treated as a new action by a downstream ZapAn external action can run more than onceUse the stable delivery id for downstream deduplication
A webhook subscription reaches its TTL before renewalWorldMonitor stops sending events to that ZapExpiration is reported before the 30-day server lifetime
A trigger input is not accepted by the registry schemaSubscription registration returns a validation errorRegistry-driven fields and server-side scope validation

Key files

FileWhy to read it
integrations/…/index.jsShows the complete Zapier surface: authentication, middleware, searches, and triggers.
integrations/…/authentication.jsDefines the user connection and the API-key validity check.
integrations/…/middleware.jsDefines shared request headers and API error behavior.
shared/event-triggers.jsonDefines the shared event, filter, payload, delivery, and retry contract.
integrations/…/hooks.jsConnects 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.jsProtects alignment between the canonical registry and the Zapier app.
integrations/…/signature-v2.test.jsProtects the signed-delivery and replay-resistance contract.
integrations/…/authentication.test.jsProtects API connection and error behavior.