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

1. Navigate to Settings

   Go to App > Settings

2. Find Outbound Webhooks

   Scroll down to the Outbound webhooks section

3. Add Webhook

   Click Add new webhook to open the configuration modal

4. Configure Webhook

   Fill out the webhook configuration form:

   • Request URL
   • HTTP method (GET/POST)
   • Headers (optional)
   • Payload (for POST)
   • Trigger event
5. Save Webhook

   Click Create outbound webhook to save

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 for your environment

Configuration

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

Payload

{
  "to": "[e-mail]",
  "from": "Stormkit <[e-mail]>",
  "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

{
  "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

{
  "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 Authorization: Bearer YOUR_CF_TOKEN
Trigger When	After a cache purge

Payload

{
  "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 Authorization: token YOUR_GITHUB_TOKEN Accept: application/vnd.github.v3+json
Trigger When	After each successful deployment

Payload

{
  "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 X-API-Key: your-api-key
Trigger When	After each successful deployment

Payload

{
  "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 - Inspect webhook payloads
• requestbin.com - Debug HTTP requests
• ngrok - Test local endpoints

Testing Example

1. Create Test Endpoint

   Visit webhook.site and copy your unique URL

2. Configure Webhook

   Create an outbound webhook with the webhook.site URL

3. Trigger Deployment

   Deploy your application or trigger a test event

4. Inspect Payload

   View the received webhook data on webhook.site

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

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

Related Documentation

Auto Deployments

Configure automatic deployments

Status Checks

Run automated tests after deployment

Mailer

Configure email sending

System Variables

Available environment variables