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

# Outbound Webhooks

> Trigger external services and workflows when deployment events occur using outbound webhooks.

## Overview

Outbound webhooks allow you to trigger external services when deployment events occur. Use webhooks to:

* Send notifications (Slack, Discord, email)
* Trigger CI/CD pipelines
* Invalidate external caches
* Update project management tools
* Run custom workflows

## Setting Up Webhooks

<Steps>
  <Step title="Navigate to Settings">
    Go to **App** > **Settings**
  </Step>

  <Step title="Find Outbound Webhooks">
    Scroll down to the **Outbound webhooks** section
  </Step>

  <Step title="Add Webhook">
    Click **Add new webhook** to open the configuration modal
  </Step>

  <Step title="Configure Webhook">
    Fill out the webhook configuration form:

    * Request URL
    * HTTP method (GET/POST)
    * Headers (optional)
    * Payload (for POST)
    * Trigger event
  </Step>

  <Step title="Save Webhook">
    Click **Create outbound webhook** to save
  </Step>
</Steps>

## Webhook Events

Choose when your webhook should be triggered:

### After Each Successful Deployment

Triggered after every successful deployment. A successful deployment means your code has been built and deployed without errors.

**Timing**: Occurs before status checks are run.

**Use cases**:

* Send success notifications
* Trigger cache purges
* Update deployment dashboards

### After Each Failed Deployment

Triggered after every failed deployment.

**Timing**: Occurs before status checks are run.

**Use cases**:

* Send error alerts
* Create incident tickets
* Notify on-call engineers

### After a Deployment is Published

Triggered when a deployment is published to an environment.

**Timing**: Occurs after status checks are run.

**Use cases**:

* Notify production releases
* Update release notes
* Trigger smoke tests

### After a Cache Purge

Triggered when cache is purged. Cache purge occurs after:

* A deployment is published
* Snippet operations
* Environment configuration updates

**Use cases**:

* Invalidate external CDN caches
* Update cache-dependent services

## Webhook Variables

When using POST requests, you can include dynamic variables in your payload. Variables are replaced with actual values when the webhook is triggered.

| Variable                       | Description                  | Example                                                 |
| ------------------------------ | ---------------------------- | ------------------------------------------------------- |
| `$SK_NOW`                      | ISO 8601 formatted timestamp | `2024-03-15T10:30:00.000Z`                              |
| `$SK_NOW_UNIX`                 | Unix timestamp               | `1710497400`                                            |
| `$SK_APP_ID`                   | Application ID               | `40140`                                                 |
| `$SK_ENVIRONMENT`              | Environment name             | `production`                                            |
| `$SK_DEPLOYMENT_ID`            | Deployment ID                | `591950`                                                |
| `$SK_DEPLOYMENT_ENDPOINT`      | Preview URL                  | `https://my-app--591950.stormkit.dev`                   |
| `$SK_DEPLOYMENT_LOGS_ENDPOINT` | Logs URL (requires auth)     | `https://app.stormkit.io/apps/40140/deployments/591950` |
| `$SK_DEPLOYMENT_STATUS`        | Deployment status            | `success` or `failed`                                   |

## Webhook Examples

### Send Email on Deployment Failure

Send an email notification when a deployment fails using Stormkit's mailer API.

#### Prerequisites

* Create an environment-level API key (**Environment** > **Config** > **API Keys**)
* [Configure mailer](/features/mailer) for your environment

#### Configuration

| Field          | Value                                                                 |
| -------------- | --------------------------------------------------------------------- |
| Request URL    | `https://api.stormkit.io/v1/mail`                                     |
| Request Method | `POST`                                                                |
| Headers        | `Content-Type: application/json`<br />`Authorization: <your-api-key>` |
| Trigger When   | After each failed deployment                                          |

#### Payload

```json theme={null}
{
  "to": "team@example.org",
  "from": "Stormkit <noreply@example.org>",
  "subject": "Deployment Failed - $SK_ENVIRONMENT",
  "body": "<h2>Deployment Failed</h2><p>Environment: $SK_ENVIRONMENT</p><p>Deployment ID: $SK_DEPLOYMENT_ID</p><p>Time: $SK_NOW</p><p><a href='$SK_DEPLOYMENT_LOGS_ENDPOINT'>View Logs</a></p>"
}
```

### Slack Notification

Send a Slack message when deployment succeeds.

#### Configuration

| Field          | Value                                               |
| -------------- | --------------------------------------------------- |
| Request URL    | `https://hooks.slack.com/services/YOUR/WEBHOOK/URL` |
| Request Method | `POST`                                              |
| Headers        | `Content-Type: application/json`                    |
| Trigger When   | After each successful deployment                    |

#### Payload

```json theme={null}
{
  "text": "Deployment Successful",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": ":white_check_mark: *Deployment Successful*\n*Environment:* $SK_ENVIRONMENT\n*Deployment ID:* $SK_DEPLOYMENT_ID\n*Preview:* <$SK_DEPLOYMENT_ENDPOINT|View Deployment>"
      }
    }
  ]
}
```

### Discord Notification

Send a Discord embed when deployment is published.

#### Configuration

| Field          | Value                                           |
| -------------- | ----------------------------------------------- |
| Request URL    | `https://discord.com/api/webhooks/YOUR/WEBHOOK` |
| Request Method | `POST`                                          |
| Headers        | `Content-Type: application/json`                |
| Trigger When   | After a deployment is published                 |

#### Payload

```json theme={null}
{
  "embeds": [{
    "title": "Deployment Published",
    "color": 5814783,
    "fields": [
      {
        "name": "Environment",
        "value": "$SK_ENVIRONMENT",
        "inline": true
      },
      {
        "name": "Deployment ID",
        "value": "$SK_DEPLOYMENT_ID",
        "inline": true
      },
      {
        "name": "Endpoint",
        "value": "$SK_DEPLOYMENT_ENDPOINT"
      }
    ],
    "timestamp": "$SK_NOW"
  }]
}
```

### Cloudflare Cache Purge

Invalidate Cloudflare cache when deployment is published.

#### Configuration

| Field          | Value                                                                       |
| -------------- | --------------------------------------------------------------------------- |
| Request URL    | `https://api.cloudflare.com/client/v4/zones/YOUR_ZONE_ID/purge_cache`       |
| Request Method | `POST`                                                                      |
| Headers        | `Content-Type: application/json`<br />`Authorization: Bearer YOUR_CF_TOKEN` |
| Trigger When   | After a cache purge                                                         |

#### Payload

```json theme={null}
{
  "purge_everything": true
}
```

### GitHub Deployment Status

Create a GitHub deployment status (requires GitHub App or token).

#### Configuration

| Field          | Value                                                                                                                        |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Request URL    | `https://api.github.com/repos/OWNER/REPO/deployments`                                                                        |
| Request Method | `POST`                                                                                                                       |
| Headers        | `Content-Type: application/json`<br />`Authorization: token YOUR_GITHUB_TOKEN`<br />`Accept: application/vnd.github.v3+json` |
| Trigger When   | After each successful deployment                                                                                             |

#### Payload

```json theme={null}
{
  "ref": "main",
  "environment": "$SK_ENVIRONMENT",
  "description": "Deployment $SK_DEPLOYMENT_ID",
  "auto_merge": false
}
```

### Custom API Endpoint

Trigger your own API endpoint with deployment data.

#### Configuration

| Field          | Value                                                           |
| -------------- | --------------------------------------------------------------- |
| Request URL    | `https://api.yourservice.com/deployments`                       |
| Request Method | `POST`                                                          |
| Headers        | `Content-Type: application/json`<br />`X-API-Key: your-api-key` |
| Trigger When   | After each successful deployment                                |

#### Payload

```json theme={null}
{
  "event": "deployment.success",
  "timestamp": $SK_NOW_UNIX,
  "data": {
    "app_id": "$SK_APP_ID",
    "environment": "$SK_ENVIRONMENT",
    "deployment_id": "$SK_DEPLOYMENT_ID",
    "status": "$SK_DEPLOYMENT_STATUS",
    "preview_url": "$SK_DEPLOYMENT_ENDPOINT",
    "logs_url": "$SK_DEPLOYMENT_LOGS_ENDPOINT"
  }
}
```

## Best Practices

### Security

* Use HTTPS endpoints only
* Store sensitive tokens in environment variables
* Rotate webhook secrets regularly
* Validate webhook signatures when possible

### Reliability

* Handle webhook failures gracefully
* Implement retry logic on the receiving end
* Use idempotent operations
* Log webhook deliveries for debugging

### Performance

* Keep webhook endpoints fast (\< 5 seconds)
* Process webhooks asynchronously
* Avoid heavy processing in webhook handlers
* Use queues for long-running tasks

## Debugging Webhooks

To test webhooks, use services like:

* [webhook.site](https://webhook.site) - Inspect webhook payloads
* [requestbin.com](https://requestbin.com) - Debug HTTP requests
* [ngrok](https://ngrok.com) - Test local endpoints

### Testing Example

<Steps>
  <Step title="Create Test Endpoint">
    Visit [webhook.site](https://webhook.site) and copy your unique URL
  </Step>

  <Step title="Configure Webhook">
    Create an outbound webhook with the webhook.site URL
  </Step>

  <Step title="Trigger Deployment">
    Deploy your application or trigger a test event
  </Step>

  <Step title="Inspect Payload">
    View the received webhook data on webhook.site
  </Step>
</Steps>

## Webhook Delivery

Stormkit attempts to deliver webhooks with the following behavior:

* **Timeout**: 30 seconds
* **Retry**: No automatic retries
* **Status codes**: 2xx considered successful
* **Failures**: Logged but do not block deployment

<Warning>
  Webhook failures do not fail the deployment. Ensure your webhook endpoints are reliable or implement your own retry mechanism.
</Warning>

## Related Documentation

<CardGroup cols={2}>
  <Card title="Auto Deployments" icon="rotate" href="/deployments/auto-deployments">
    Configure automatic deployments
  </Card>

  <Card title="Status Checks" icon="check-circle" href="/deployments/status-checks">
    Run automated tests after deployment
  </Card>

  <Card title="Mailer" icon="envelope" href="/features/mailer">
    Configure email sending
  </Card>

  <Card title="System Variables" icon="code" href="/deployments/system-variables">
    Available environment variables
  </Card>
</CardGroup>