Integration Lifecycle Hooks

Patrol emits lifecycle hooks at key moments during its provisioning and deployment pipelines. These hooks are the foundation of the integration workflow system — they let you attach outgoing actions (like updating a CRM or notifying a CMDB) to specific points in the process.

Available hooks

Hook	Fired when	Typical use
customer.created	A new Customer record is saved (e.g. from a HubSpot deal)	Write the new Patrol customer ID back to HubSpot
customer.found	An existing Customer is matched during a find-or-create flow	Update CRM with latest Patrol status
environment.created	A new Environment is saved and (if configured) an auto-deploy has been queued	Register the environment in an external system
deployment.succeeded	A deployment run transitions to succeeded	Notify ServiceNow CMDB, update CRM deal status
deployment.failed	A deployment run transitions to failed	Alert external incident management

Context payload

Every lifecycle hook carries a typed context object containing the relevant entities. Outgoing workflow steps use field-mapping syntax to extract values from this context.

{
  tenant:      { id }
  customer:    { id, name, hubspotCompanyId }
  environment: { id, name, provider, region, envType, serviceTemplateId }
  run:         { id, finishedAt, externalRunId, status, error }
  integration: { id, type }
}

Not every hook includes every section — customer.created won’t have a run, for example. Only fields relevant to the event are populated.

Field mapping syntax

When configuring a workflow step’s field mapping, use dot-notation paths into the context object:

Path	Resolves to
customer.id	The Patrol customer UUID
customer.name	Customer display name
environment.id	The Patrol environment UUID
environment.provider	Cloud provider string (e.g. aws, azure)
run.externalRunId	The CI/CD system’s run identifier

Literal values (strings without a dot) are passed through unchanged — useful for setting fixed status values like provisioning or live.

How hooks are emitted

Hooks are emitted via NestJS’s EventEmitter2 in a fire-and-forget pattern. The service that creates or transitions the entity emits the event; the workflow executor listens and processes matching workflows asynchronously.

• customer.created / customer.found — emitted from the HubSpot inbound handler after resolving or creating the customer
• environment.created — emitted from the HubSpot inbound handler after creating the environment
• deployment.succeeded / deployment.failed — emitted from RunFinalizerService after atomically transitioning a run to its terminal status

Scoping

Workflows are tenant-scoped by default and can be optionally narrowed to a specific service template. When a lifecycle event fires, Patrol loads all enabled workflows for the tenant where:

• serviceTemplateId is null (tenant-wide), or
• serviceTemplateId matches the environment’s template

Template-specific workflows merge with tenant-wide workflows — they don’t replace them. To suppress a tenant-wide workflow for a specific template, disable it at the template level.

Next steps

• Setting up integration workflows — step-by-step guide to creating your first workflow
• HubSpot integration — connecting HubSpot as an inbound trigger source