# Outgoing Webhook Notifications

Configure Valohai to automatically send notifications to external services when executions, pipelines, or deployments change state. Perfect for integrating with Slack, custom dashboards, or triggering downstream processes.

{% hint style="info" %}
**Note:** This guide covers notifications sent **from Valohai to external services**. If you want to receive webhooks **into Valohai** to launch workflows, see [Webhook Triggers](/automation-overview/triggers/webhooks.md).
{% endhint %}

***

## What Are Outgoing Webhooks?

Outgoing webhooks let Valohai push notifications to your application when state changes occur. Unlike triggers (which receive webhooks to start work), outgoing webhooks send data out when work completes.

**Common use cases:**

* Post execution status to Slack channels
* Update external monitoring dashboards
* Trigger downstream processes in other systems
* Log events to external analytics platforms
* Send alerts to on-call systems

***

## Supported Events

Valohai can send notifications for these events:

* Execution completes or fails
* Task completes or fails
* Pipeline completes or fails
* Deployment completes or fails

You can configure separate webhooks for different event types and route them to different channels.

***

## Quick Start: Slack Integration

The easiest way to get started is sending notifications to Slack.

### Step 1: Create a Slack Webhook

1. Follow the [Slack webhook documentation](https://api.slack.com/messaging/webhooks) to create an incoming webhook
2. Complete the first 3 steps (create app, enable incoming webhooks, create webhook URL)
3. Copy the generated Webhook URL (looks like `https://hooks.slack.com/services/T00.../B00.../xxxxx`)

### Step 2: Configure in Valohai

1. Open your project settings
2. Navigate to **Notifications** tab
3. Click **Channels** → **Create a new channel**
4. Select type: **Slack**
5. Paste your Slack webhook URL
6. Give the channel a name (e.g., "team-ml-alerts")
7. Save the channel

### Step 3: Create Notification Routing

1. Still in **Notifications** tab, click **Project Notifications**
2. Click **Create new notification routing**
3. **Event:** Select your desired event (e.g., "execution completes")
4. **Channel:** Select your Slack channel
5. Save the routing

Now Valohai will automatically post to Slack when the event occurs!

***

## Custom Webhook Integration

You can send notifications to any service that accepts HTTP POST requests.

### Step 1: Create a Custom Channel

1. Project Settings → Notifications → Channels
2. Click **Create a new channel**
3. **Type:** Select "Custom"
4. **Name:** Give your channel a descriptive name
5. **Webhook URL:** Enter your endpoint URL
6. **Headers (optional):** Add authentication headers if needed
   * Example: `Authorization: Bearer YOUR_TOKEN`
7. Save the channel

### Step 2: Create Notification Routing

1. Navigate to **Project Notifications**
2. Click **Create new notification routing**
3. Select your event and custom channel
4. Save the routing

{% hint style="info" %}
**Automate workflows without code:** Use services like [IFTTT](https://ifttt.com/explore) or [Zapier](https://zapier.com/) as webhook receivers to connect Valohai with hundreds of other tools.
{% endhint %}

***

## Webhook Payload Structure

Valohai sends a JSON payload with event details. Here's an example for a completed execution:

```json
{
  "project": "016f3203-4a8c-969e-078c-52ab66947746",
  "title": "Execution finished: demo/cool-tensorflow/#736 (completed)",
  "type": "execution_completed",
  "body": "Execution [demo/cool-tensorflow/#736](https://app.demo.com/p/valohai/cool-tensorflow/execution/0178f482-8686-fb28-8af1-3d36af38079d/) (by demouser)\nfinished with duration 11:01.",
  "url": "/p/demo/cool-tensorflow/execution/0178f482-8686-fb28-8af1-3d36af38079d/",
  "data": {
    "valohai.execution-counter": 736,
    "valohai.execution-ctime": "2021-04-21T12:58:18.119973+00:00",
    "valohai.execution-duration": 660.0186445713043,
    "valohai.execution-id": "0178f482-8686-fb28-8af1-3d36af38079d",
    "valohai.execution-qtime": "2021-04-21T12:58:18.201116+00:00",
    "valohai.execution-status": "complete",
    "valohai.execution-step": "Train model (MNIST)",
    "valohai.execution-title": null,
    "valohai.project-id": "016f3203-4a8c-969e-078c-52ab66947746",
    "valohai.project-name": "demo/cool-tensorflow",
    "valohai.creator-id": 3323,
    "valohai.creator-name": "demouser",
    "valohai.commit-identifier": "4d34124453b680daa0ecb881bcf1bd735a3bf99d"
  }
}
```

### Key Fields

* **`type`:** Event type (e.g., `execution_completed`, `pipeline_failed`)
* **`title`:** Human-readable event description
* **`body`:** Formatted message text (often with markdown links)
* **`url`:** Relative URL to the resource in Valohai
* **`data`:** Structured metadata about the event

Use these fields to build custom integrations that extract the information you need.

***

## Debugging Webhook Deliveries

### Test Your Webhook

Before setting up routing, verify your webhook endpoint works:

1. Use a tool like [Postman](https://www.postman.com/) or `curl`
2. Send a test POST request with sample JSON
3. Confirm your endpoint receives and processes it correctly

```shell
curl -X POST https://your-webhook-url.com \
  -H "Content-Type: application/json" \
  -d '{"type":"test","title":"Test notification"}'
```

### Monitor Delivery Status

Valohai logs webhook delivery attempts:

1. Go to Project Settings → Notifications
2. Check the webhook delivery logs
3. Look for failed deliveries and error messages

{% hint style="warning" %}
**Webhook endpoint requirements:**

* Must return 2xx status code to be considered successful
* Should respond within 30 seconds
* Must accept JSON payloads via POST
  {% endhint %}

***

## Security Considerations

### Authentication

For custom webhooks, always use authentication:

* **API tokens:** Include in headers (`Authorization: Bearer TOKEN`)
* **Shared secrets:** Validate request origin
* **IP allowlisting:** Restrict to Valohai's IP ranges

### HTTPS Only

Always use HTTPS endpoints, never HTTP. This ensures:

* Data is encrypted in transit
* Authenticity of your endpoint
* Protection against man-in-the-middle attacks

### Token Management

Store webhook URLs and auth tokens securely:

* Don't commit them to version control
* Use environment variables or secret managers
* Rotate tokens regularly
* Use minimum required permissions

***

## Next Steps

* **Need to receive webhooks?** Check out [Webhook Triggers](/automation-overview/triggers/webhooks.md)
* **Want event-driven workflows?** Explore [Notification Triggers](/automation-overview/triggers/notification-triggers.md)
* **Building custom integrations?** See the [REST API Guide](https://github.com/valohai/dokuhai/blob/main/docs/how-to/automation/triggers/notifications/broken-reference/README.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.valohai.com/automation-overview/outgoing-webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.