> ## 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.

# Receiving a trigger event

> Define the event handler for a trigger block

`defineWorkflowBlockTrigger` wires an event handler to a trigger block. The handler runs once for each incoming request to `metadata.triggerCallbackUrl`, the URL registered with the upstream service during activation.

Here you decide whether the event should start a workflow run, and (if so) what outcome data to send into the workflow.

## Parameters

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

<ParamField path="trigger" type="function" required>
  The handler function. Receives the raw `req` (a standard `Request` object) and a context object with `config` (typed from the block's configSchema) and `metadata`.

  `metadata` provides workflow identity context for the incoming event:

  | 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` | ID of the activation that registered this callback. Matches the value passed to `activate`. |
  | `triggerCallbackUrl` | `string` | The URL incoming events are sent to.                                                        |
  | `workflowTitle`      | `string` | Human-readable title of the workflow.                                                       |
  | `workflowUrl`        | `string` | Link to the workflow in the Attio UI.                                                       |
</ParamField>

## Example

```ts trigger.ts theme={"system"}
import {Workflows} from "attio/server"
import block from "./block"

export default Workflows.defineWorkflowBlockTrigger(block, async (req, {config, metadata}) => {
  const signature = req.headers.get("x-signature")

  if (!verifySignature(signature, config.secret)) {
    // Invalid signature — silently drop the request
    return {type: "no-op"}
  }

  const payload = await req.json()

  if (!payload.eventType) {
    // Event not relevant — skip without starting a run
    return {type: "no-op"}
  }

  // Start a workflow run down the "triggered" branch
  return {type: "outcome", id: "triggered", data: null}
})
```

## See also

* [Registering a trigger](./define-workflow-block-activate): trigger activate handler
* [Outcome schema](./outcome-schema): typing the data field in return values
* [File structure](./file-structure): complete folder layout for trigger and step blocks