Registering a trigger

Define the activate handler for a trigger block

defineWorkflowBlockActivate wires an activate handler to a trigger block. The handler runs once when a workflow that uses this trigger is enabled.

Typical work here: register a webhook with the upstream service so events flow back to Attio via metadata.triggerCallbackUrl.

Parameters

block · WorkflowBlock · required

The block returned by defineWorkflowBlock in block.ts.

activate · function · required

The handler function. Receives a context object with config (typed from the block’s configSchema) and metadata.

metadata provides workflow identity and the callback URL to register with the upstream service:

Field	Type	Description
workflowId	string	ID of the workflow this block belongs to.
workflowVersionId	string	ID of the active workflow version.
workflowBlockId	string	ID of this block instance within the workflow.
uniqueActivationId	string	Unique ID for this activation. Store it alongside the webhook registration so you can look it up during deactivation.
workflowTitle	string	Human-readable title of the workflow.
workflowUrl	string	Link to the workflow in the Attio UI.
triggerCallbackUrl	string	URL to register with the upstream service. Incoming requests to this URL are forwarded to your trigger.ts handler.

Example

activate.ts

import {Workflows} from "attio/server"
import block from "./block"

export default Workflows.defineWorkflowBlockActivate(block, async ({config, metadata}) => {
  const response = await fetch("https://api.example.com/webhooks", {
    method: "POST",
    headers: {"Content-Type": "application/json"},
    body: JSON.stringify({
      url: metadata.triggerCallbackUrl,
      ref: metadata.uniqueActivationId,
    }),
  })

  if (!response.ok) {
    return {type: "error", errorMessage: "Failed to register webhook"}
  }

  return {type: "complete"}
})

See also

• Receiving a trigger event: trigger event handler
• Deactivating a trigger: trigger deactivate handler
• File structure: complete folder layout for trigger and step blocks