Skip to main content
POST
Create trigger

Authorizations

Authorization
string
header
required

Pass your pk_live_... API key as a Bearer token.

Body

application/json
kind
required

What the trigger fires on — one or more kind ids from GET /triggers/kinds, or a single id as shorthand. Kinds come in two families: connector data kinds (e.g. email, calendar_event) that fire on events from your connected accounts, and entity kinds (e.g. person, organization) that fire when an extracted entity of that type changes. Use '*' to match every kind.

Example:
action
enum<string>
required

Which change to fire on. created/updated/deleted are lifecycle changes to the underlying record. observed fires whenever an entity of the given kind is seen in evidence, even if nothing about it changed — useful for entity kinds. '*' matches any action.

Available options:
observed,
created,
updated,
deleted,
*
delivery
WebhookDelivery · object
required
name
string | null

Optional display name to tell your triggers apart in lists and the console. Purely cosmetic — it has no effect on matching or delivery.

Required string length: 1 - 128
Example:

"New-hire emails from recruiting"

filter
Filter · object | null

Optional predicate for deeper rules — narrow the trigger beyond kind + action by matching against fields on the event payload. A leaf clause is {"field": "<dotted.path>", "op": "<operator>", "value": ...}; operators are eq, ne, exists, contains, starts_with, ends_with, regex, in, includes, domain_matches, and gt/lt/gte/lte. Clauses compose via all / any / not, nested to any depth. The fields you can reference are listed on each kind's predicate_fields in GET /triggers/kinds. For entity kinds with action: observed, filter on entity_urnexists fires only for observations that resolved to a known entity, eq scopes to one specific entity — or on via (identity = structured field like a sender or attendee, content = name found in body text).

Example:
entity_observation_fuzzy
boolean
default:false

For observed-action triggers on entity kinds, also match name variants and minor misspellings — not just exact aliases. Ignored on other kinds and actions.

enabled
boolean
default:true

Response

Successful Response

id
string
required
user_id
string
required
kind
string[]
required

Kind ids this trigger fires for; ['*'] means any kind.

action
string
required
delivery
Delivery · object
required
enabled
boolean
required
name
string | null

Display name, if you set one.

filter
Filter · object | null
entity_observation_fuzzy
boolean
default:false

Whether fuzzy-matched entity observations are accepted in addition to exact matches.

secret
string | null

Webhook signing secret, returned only in the create response — store it. Each delivery carries an 'Adapter-Signature: v1=' header; verify it by computing HMAC-SHA256 over '.' with this secret and comparing hex digests. Reject deliveries whose timestamp is older than your replay window.

created_at
string<date-time> | null
updated_at
string<date-time> | null
last_fired_at
string<date-time> | null

When this trigger last matched an event and delivery was attempted, including failed deliveries.

last_status
enum<string> | null

Outcome of your most recent delivery. Null until the trigger first fires.

Available options:
delivered,
failed
consecutive_failures
integer
default:0

Consecutive events that failed to deliver, counted once per event after its final retry. Resets to 0 on success. At 50 the trigger is disabled automatically.

auto_disabled_at
string<date-time> | null

Set when the trigger was disabled automatically after 50 consecutive events failed to deliver. Fix your endpoint, then update the trigger with enabled=true to resume.