> For the complete documentation index, see [llms.txt](https://docs.erathos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.erathos.com/api/introduction/trigger-jobs-outside-erathos.md).

# Trigger jobs outside Erathos

<div data-full-width="false"><figure><img src="https://1678877911-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcoXXr5bUdZsSICKNKPP1%2Fuploads%2Fgit-blob-f6283ea52f227b9f55f7ea074d6227ac151eee66%2FCopy%20of%20Untitled%20drawing.jpg?alt=media" alt=""><figcaption></figcaption></figure></div>

An orchestration webhook is an HTTP request Erathos sends after a job's run finishes, to start the next step in another tool: an Airflow DAG, a dbt Cloud job, a Databricks workflow, or your own API. It's sent once for each table the run synced, so a job with nested tables sends one request per table (see [Rules](https://docs.erathos.com/api/concepts/rules.md) to send it only once).

To register a webhook, you need to provide the following information:

* **description**: A text description to help identify the functionality of the webhook.
* **jobs**: A list of Job IDs (UUIDs) the webhook fires for. These IDs can be found through the Jobs endpoint in the workspace.
* **connections**: A list of connection IDs (UUIDs). The webhook fires for **every job of each connection, including jobs added to it later**. Use it when you want a whole connection covered rather than listing its jobs one by one.
* **method**: The type of HTTP request (GET, POST, PUT, PATCH, DELETE).
* **url**: The destination URL where the webhook will be sent. It must start with `http://` or `https://`.
* **header**: Additional fields to include in the request, such as Content-Type and Authorization.
* **body**: The request body, which can include static or dynamic data, using execution metadata.
* **rules**: A list of conditions that must be met for the webhook to be triggered. All rules must be satisfied for the webhook to be sent; with no rules, it's sent after every run, successful or failed.
  * **variable\_name**: The name of the metadata variable (check the [Metadata](https://docs.erathos.com/api/concepts/metadata.md) section).
  * **operation**: One of the accepted operations depending on the variable type (check the [Rules](https://docs.erathos.com/api/concepts/rules.md) section).
  * **value**: A string, or for `IN` and `NOT_IN` a list of strings.

A webhook needs at least one job or one connection, and it can have both. A job covered both ways sends the webhook only once.

{% hint style="info" %}
When you update a webhook, leaving `jobs` or `connections` out of the request keeps its current ones. Send an empty list to remove them all.
{% endhint %}

### Dynamic values

The **url**, **header**, and **body** fields can include references that are replaced with real values before the webhook is sent:

* `${{variables.NAME}}`: a [variable](https://docs.erathos.com/api/concepts/variables-and-secrets.md) registered in the workspace.
* `${{secrets.NAME}}`: a [secret](https://docs.erathos.com/api/concepts/variables-and-secrets.md) registered in the workspace. Use secrets for every credential, such as API tokens.
* `${{erathos.NAME}}`: metadata from the run that triggered the webhook (check the [Metadata](https://docs.erathos.com/api/concepts/metadata.md) section).

A few rules apply to references:

* They start with `$`: `{{variables.NAME}}` without it is sent as written.
* They can go anywhere in the url, the host included, e.g. `https://${{variables.AIRFLOW_HOST}}/api/v1/dags`.
* Names are case-insensitive.
* A reference to a variable, secret or metadata field that doesn't exist is sent as written, so check names carefully.

{% hint style="warning" %}
Webhooks can only be sent to public addresses. A url that points to a private, loopback or link-local address (such as `localhost`, `10.0.0.5` or `169.254.169.254`) is refused when the webhook is sent, including after a redirect.
{% endhint %}

### Example

Below is an example of a webhook that triggers the execution of a DAG in Airflow after the successful completion of a Job, with execution between 00:00 and 08:00 UTC on weekdays, and only if at least one record has been transferred:

```json
{
    "description": "airflow_trigger_example",
    "is_active": true,
    "jobs": [
        "uuid_1",
        "uuid_2",
        ...,
        "uuid_n"
    ],
    "method": "POST",
    "url": "https://${{variables.AIRFLOW_HOST}}/api/v1/dags/${{erathos.job_id}}/dagRuns",
    "header": {
        "Content-Type": "application/json",
        "Authorization": "Basic ${{secrets.AIRFLOW_KEY}}"
    },
    "body": {
        "conf": {
            "name": "${{erathos.table_name}}",
            "status": "${{erathos.status}}"
        }
    },
    "rules": [
        {
            "variable_name": "STATUS",
            "operation": "EQUAL",
            "value": "FINISHED"
        },
        {
            "variable_name": "ROWS",
            "operation": "GREATER_THAN",
            "value": "0"
        },
        {
            "variable_name": "FINISHED_AT_TIME",
            "operation": "GREATER_THAN",
            "value": "00:00"
        },
        {
            "variable_name": "FINISHED_AT_TIME",
            "operation": "LESS_THAN",
            "value": "08:00"
        },
        {
            "variable_name": "FINISHED_AT_WEEKDAY",
            "operation": "NOT_IN",
            "value": ["0", "6"]
        }
    ]
}
```

{% hint style="info" %}
More examples are available in the [Templates section](https://docs.erathos.com/api/quickstart.md).
{% endhint %}

After building your webhook, send a request to the [**Create Webhook** endpoint](https://docs.erathos.com/api/api-reference/orchestration.md#developers-workspaces-workspace_id-orchestration-webhooks-1) to register it.

{% hint style="info" %}
You can also create and manage webhooks through an AI agent connected to the [Erathos MCP server](https://docs.erathos.com/platform/mcp.md), and see what each webhook did after each run there.
{% endhint %}
