Runtime, workers, and webhooks
Model worker provisioning, connector synchronization, and inbound webhook handling as observable lifecycle systems.
Worker provisioning, connector synchronization, and webhook delivery are asynchronous operations. A successful create request does not always mean that a runtime is ready, an external source has been discovered, or a sync has completed. Treat each system as a stateful lifecycle with a resource ID, visible activity, and recoverable failure path.
Hosted Worker lifecycle
/v1/workers is the organization-managed Worker family. It is optional for a local desktop workspace. Use it only when a deployment needs a hosted or remotely managed iPolloWork runtime.
The create operation can return either an immediate creation state or an accepted asynchronous state. Read the Worker and runtime status before assuming it is usable.
- 01Create
POST a Worker with its name and destination. Optional fields describe the workspace, sandbox, or image selection.
- 02Provision
Handle the declared 201 or 202 response and retain the `wrk_` resource ID.
- 03Inspect
Read the Worker, activity heartbeat, or runtime representation to establish readiness.
- 04Operate
Request a runtime token or upgrade only after the runtime reports a valid operational state.
Worker routes to model explicitly
| Need | Route family | Client behavior |
|---|---|---|
| List or create | /v1/workers | Use cursor pagination. Creation requires a name and destination. |
| Read state | /v1/workers/{id} | Treat the Worker ID as durable. Do not re-find it by display name. |
| Observe liveness | /v1/workers/{id}/activity-heartbeat | Use it as an activity signal, not a promise that a task completed. |
| Read or upgrade runtime | /v1/workers/{id}/runtime, /runtime/upgrade | Re-read state after an upgrade request. |
| Request access token | /v1/workers/{id}/tokens | A 409 can mean the Worker is not ready. Retry only after inspecting readiness. |
Connector graph
Connectors represent an external system in layers. An account proves a connection identity. An instance defines how that account is used. Targets, mappings, discovery, and sync events then describe the work performed against external data.
Each layer produces a different identifier and failure mode. Keep the graph intact so an operator can retry the right object.
Who may connect
An authorized external identity or connection account.
How the integration is used
A configured integration that can be enabled, disabled, discovered, and given targets.
A scoped external location selected for import or sync.
What the system did
A relationship between synchronized or imported resource representations.
Observable activity with a retryable failure path.
GitHub setup and webhooks
The GitHub connector has dedicated setup, installation, account, repository, and validation routes beneath /v1/connectors/github/*. Inbound delivery reaches POST /v1/webhooks/connectors/github.
Build the surrounding service as a narrow ingress boundary:
- Keep the endpoint reachable only through the organization ingress policy.
- Use the request verification behavior and response schemas in the checked-out OpenAPI contract and connector implementation. Do not invent a signature scheme in the caller.
- Acknowledge only after the receiving service can persist or safely queue the event.
- Correlate the delivery with the connector instance, target, and resulting sync event where the API exposes them.
- Return an observable error state for unavailable dependencies instead of silently dropping an event.
The OpenAPI specification declares 200, 202, 401, and 503 outcomes for the GitHub webhook operation. Treat 202 as accepted asynchronous work, and investigate 503 at the connector or dependency boundary before retrying from the sender.
An operational recovery loop
The same pattern works for an unready Worker, a failed sync event, or an accepted webhook delivery.
- 01Capture identity
Keep the Worker, account, instance, target, event, or delivery ID returned by the API.
- 02Read status
Inspect the resource, runtime, activity, or sync event before sending a second write.
- 03Correct boundary
Repair credentials, configuration, readiness, or dependency health at the owning layer.
- 04Retry narrowly
Repeat the specific operation and confirm its resulting state or artifact.
For resource access and authentication scope, read Authentication and access. For the complete request bodies and response schemas, use packages/docs/openapi.json from the same iPolloWork revision you are integrating.