Skip to main content

Zapier

The Evinor app for Zapier starts a Zap each time a sensor fires, collects new entries from a beat, finds entities, and files reports. Its New Sensor Event trigger connects itself to the sensor as a connected app and verifies every delivery for you, so you don't paste a Catch Hook URL into the sensor or handle signatures yourself.

The app is invite-only while it is in beta. To request access, email hi@evinor.ai. Its source is public at evinor-ai/zapier-evinor.

What the app offers​

StepWhat it does
New Sensor Event (instant)Starts a Zap when a sensor matches an event. Turning the Zap on connects it to the sensor.
New Beat Entry (polling)Reads the beat's entries from the last 24 hours, newest first. Reading entries is not charged.
Find Entity (search)Finds an entity by name and returns the first match, for example to fill a File a Report role.
File a Report (action)Files a first-hand report: pick an event type, then fill one field per role. See File a Report.

Connect your account​

Connect with an Evinor API key (see Authentication). Give the key the scopes for the steps you use:

ScopeUsed for
SENSORS_READNew Sensor Event: listing your sensors
SENSORS_WRITENew Sensor Event: connecting and removing the destination
BEATS_READNew Beat Entry
REPORTS_READFind Entity, and the event types File a Report lists
REPORTS_WRITEFile a Report

REPORTS_WRITE is sales-gated and granted on request (hi@evinor.ai). Zapier tests the connection with GET /v1/sensors?limit=1, so a key without it still connects and every other step works. File a Report then fails with the API's missing-scope message, which names the scope.

The connection is labelled with the key's last four characters only. When the API rejects a request, Zapier shows the problem's detail.

Connect a sensor​

  1. In the Evinor web app, open the sensor's Delivery step, click + Zapier, and save the sensor. The sensor now has a destination waiting for Zapier, so it can be saved without any other destination.
  2. In Zapier, create a Zap with the Evinor app and its New Sensor Event trigger.
  3. Sign in with an Evinor API key that has the SENSORS_READ and SENSORS_WRITE scopes.
  4. Pick the sensor.
  5. Turn the Zap on. The waiting destination becomes Zapier · Connected · hooks.zapier.com.

You can skip + Zapier for a sensor that already has another destination: turning the Zap on adds the Zapier destination by itself.

How the connection works​

  • Turning the Zap on connects a destination for the Zap's hook URL (POST /v1/sensors/{id}/destinations with "app": "zapier"). If the sensor has a waiting Zapier destination, the connection fills it; otherwise a new destination is added. A sensor holds at most 10 destinations. A disabled sensor is listed with a note; you can connect to it, and it delivers once it is enabled. In the Evinor web app the destination reads Zapier · Connected · hooks.zapier.com.
  • Turning the Zap off removes the destination. If it was the sensor's only destination, it reverts to a waiting Zapier destination. A destination you already removed in Evinor counts as removed, so turning the Zap off never fails on it.
  • Turning the Zap on again connects again, with a new destination id and a new signing secret. If Zapier reuses the same hook URL and a destination for it was left behind, the new connection replaces it instead of failing.
  • Disconnecting in Evinor stops deliveries at once, but the Zap stays on in Zapier. To reconnect, turn the Zap off and on again.

Two Zaps on the same sensor have two hook URLs, so they get two separate destinations. If turning the Zap on fails, Zapier shows the reason from the API: a sensor that already has 10 destinations, or a hook URL already used by a different destination, returns 409 state-conflict; an unknown sensor returns 404 not-found.

Signature verification​

Turning the Zap on stores the destination's id, signing secret and key_id with the Zap. Every delivery is then checked before a Zap run starts, in this order:

  1. The stored signing details and the envelope's fields are present.
  2. The X-Evinor-Signature header, if Zapier forwarded it, equals the body's sender.signature.
  3. The signature is strict base64.
  4. sender.keyId is the key_id issued for this Zap.
  5. The HMAC-SHA256 over the canonical body (see Webhooks) matches, compared in constant time.
  6. timestamp is a strict ISO-8601 time within 5 minutes of now, in either direction.

A delivery that fails any check starts no Zap run, and the app logs only the name of the failed check. It never raises an error, so someone who learns the hook URL cannot fill your Zap history.

A missing signature header is accepted. This differs from the n8n node, which rejects it. The header is only a consistency check: the HMAC covers the signature inside the body, and Zapier does not guarantee that every header is forwarded. A header that is present but different is still rejected.

The signing secret is visible to anyone with access to the Zap. Zapier stores it with the Zap, so a teammate who can edit the Zap can see it. It only verifies deliveries to that one hook URL. The app never writes it, or any delivery, to its logs.

Testing the trigger​

Testing New Sensor Event in the Zap editor shows one built-in sample event with is_test: true. It is synthetic, never real event data. It makes no API call, consumes no credits and needs no sensor activity.

New Sensor Event output​

Each delivery is flattened so its fields are easy to pick in Zapier:

FieldMeaning
idThe delivery's idempotencyKey, the same for every retry of one delivery.
message_idThe delivery attempt's messageId. A retry gets a new one.
is_testtrue for the built-in sample, otherwise false.
sensor_idThe sensor that matched.
matched_atWhen the event cleared the sensor's bar.
event_idThe underlying event. One event matching several sensors shares this id.
event_dateWhen the event happened, if known.
titleA one-line description, such as "TechCorp laid off 200 people."
event_typeThe event type code, such as LAYOFF.
event_type_nameThe event type's name, such as "Layoffs".
role__<CODE>One field per role, such as role__COMPANY_NAME. Repeats are joined by , .
rawThe full event payload as a JSON string.

The signature and the rest of the sender block are never part of the output. The delivery carries no link to the event; use event_id.

Handling duplicates​

  • New Sensor Event: Zapier deduplicates on id. It stays the same across Evinor's retries of one delivery, and a delivery replayed within the 5-minute window is dropped on it too. One event that matches several sensors arrives once per sensor; use event_id to deduplicate across sensors. See Replay protection.
  • New Beat Entry: Zapier deduplicates on id, the entry id, so only new entries start a run. Entries without an event are skipped.

File a Report​

Pick an event type, then fill Happened At (required) and one field per role:

  • entity roles take an entity id (use Find Entity to look one up);
  • date roles take YYYY-MM-DD;
  • amount roles take a number and a unit (for example USD);
  • CATEGORICAL roles cannot be filed yet, so they have no field.

The event types come from GET /v1/event-types. See Reporting events for what the API checks.

Identical inputs file only one report, ever. The app sends an Idempotency-Key that is the SHA-256 of the event type, Happened At, every role value, the description, the optional Deduplication key, and the Zap's id when Zapier provides one. A retry within 24 hours gets the original report back; a later one fails with report-already-submitted.

Without a Zap id, two Zaps on the same connection with identical inputs share that one report. To file the same content again on purpose, map a changing value, such as a trigger id or a timestamp, into Deduplication key. It is hashed into the key and never sent to Evinor.