Events and Triggers¶

Inbound HTTP, jobs, GraphQL subscriptions, and error handlers all invoke server functions, but they do not all pass the same arguments. Use this page to pick the right signature.

The three-arg Event convention¶

Jobs and webhook Triggers call the server function with three positional arguments:

(eventPayload, headersPayload, paramsPayload) => …

Argument	Typical contents
`eventPayload`	Webhook: HTTP body. Job: the object configured on that job function entry
`headersPayload`	Webhook: request headers plus gateway-injected `x-http-method` and `x-original-uri` (path without query). Job: usually `{}` unless you set headers
`paramsPayload`	Webhook: values from the handle subpath template (path and query). Job: configured object

Python webhook handlers must accept those three arguments (or *args). Execution fails if the arity does not match.

Gateway-injected headers (webhook only)¶

On every webhook request Poly sets:

x-http-method: the HTTP method (req.method)
x-original-uri: the request path without the query string

Read them from headersPayload. They are not client headers. Query string is not in x-original-uri; use paramsPayload / the raw query if you need it.

Triggers¶

A Trigger is an environment-scoped binding from a source to a server function. The source is exactly one of:

a webhook handle, or
an error-handler filter (path, optional function/application/user ids)

Create them in Canopy under Triggers (Managing Triggers). Permission: Manage Triggers.

Webhook source¶

HTTP hits the handle, optional security functions run, then enabled triggers for that webhook+environment fire.

Wait for Response: if true, the HTTP client waits for that server function’s result and uses it as the response. If false, Poly returns the handle’s static responsePayload (or an empty 200) and the function still runs.

Only one trigger per webhook may have Wait for Response = true.

Error-handler source¶

When a matching function fails, the destination server function receives a single error object, not the three Event args. You cannot point an error-handler trigger at the same function that failed. See Error Handlers.

Other delivery shapes¶

Path	Server function arguments
Job	Three-arg Event (above). See Jobs
Webhook Trigger	Three-arg Event
GraphQL Subscription	Two args: `[event, params]`. That shape is canonical. See GraphQL Subscriptions
Error-handler Trigger	One enriched error object
SDK webhook listener (Socket.IO `events`)	`{ body, headers, params, executionId }` (different names)
`errorHandler` module	In-process callback. Client must stay connected. See errorHandler Module

API Endpoints vs API Functions¶

An API Endpoint (Older documentation called this a Webhook) is inbound HTTP you expose on Poly. An API Function is an outbound call Poly makes for you. Do not train an API Function when you need a public URL. See API Endpoints (Webhooks) and API Function Training.