> ## Documentation Index
> Fetch the complete documentation index at: https://docs.attio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<ParamField path="block" type="WorkflowBlock" required>
  The block returned by `defineWorkflowBlock` in `block.ts`.
</ParamField>

<ParamField path="activate" type="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.  |
</ParamField>

## Example

```ts activate.ts theme={"system"}
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](./define-workflow-block-on-trigger-callback): trigger event handler
* [Deactivating a trigger](./define-workflow-block-deactivate): trigger deactivate handler
* [File structure](./file-structure): complete folder layout for trigger and step blocks