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

# Webhooks Guide

> Set up webhooks from popular services to send notifications

## Overview

Webhooks allow you to automatically send notifications when events happen in external services. Connect your favorite tools and never miss important updates.

## How Webhooks Work

```
External Service (GitHub, Stripe, etc.)
    ↓
Event Happens (push, payment received, etc.)
    ↓
POST request to your Dashtray webhook URL
    ↓
Notification sent to your phone
    ↓
You get alerted instantly
```

## Setting Up a Webhook

1. Create a alert in Dashtray app
2. Copy your webhook URL
3. Go to the external service
4. Create a webhook pointing to your Dashtray URL
5. Customize the template in the app
6. Done! You're getting notifications

## Popular Integrations

### GitHub

Get notifications for pushes, pull requests, deployments, and more.

**Setup:**

1. Go to your repository → Settings → Webhooks
2. Click "Add webhook"
3. Paste your Dashtray webhook URL
4. Select events: Push, Pull Request, Deployment, etc.
5. Click "Add webhook"

**Example notification:**

```
🚀 Deployment successful
main → production
```

### Stripe

Get notifications for payments, disputes, subscription changes.

**Setup:**

1. Go to Stripe Dashboard → Developers → Webhooks
2. Click "Add endpoint"
3. Paste your Dashtray webhook URL
4. Select events: charge.succeeded, charge.failed, customer.created, etc.
5. Save

**Example notification:**

```
💳 Payment received
$99.00 from john@example.com
```

### Zapier

Connect 5,000+ apps to Dashtray.

**Setup:**

1. Create a Zap
2. Select trigger (any app + event)
3. Add action: "Webhooks by Zapier" → POST
4. URL: Your Dashtray webhook
5. Data: Map the fields you want
6. Test and activate

**Example:**

```
📝 New form submission
Name: John Doe
Email: john@example.com
```

### Supabase

Get notified of database changes.

**Setup:**

1. Go to Supabase → Database → Webhooks
2. Click "Create a new hook"
3. Table: Select your table
4. Events: INSERT, UPDATE, DELETE
5. HTTP request URL: Your Dashtray webhook
6. Save

### SendGrid

Monitor email delivery.

**Setup:**

1. SendGrid Dashboard → Settings → Mail Send
2. Event Webhook
3. HTTP POST URL: Your Dashtray webhook
4. Select events: Bounce, Clicked, Delivered, etc.
5. Save

### Custom Webhooks

Any service that supports webhooks can work with Dashtray.

**Requirements:**

* Webhook support (HTTP POST)
* JSON payload support
* Your webhook URL

**Example curl command:**

```bash theme={null}
curl -X POST https://dashtray.app/p/abc1234 \
  -H "Content-Type: application/json" \
  -d '{
    "event": "build.completed",
    "metadata": { "source": "my-app" }
  }'
```

## Webhook URL Format

Your webhook URL is unique to each alert:

```
https://dashtray.app/p/{short_code}
```

* Each alert gets its own 7-character code (the code **is** the credential)
* Keep it secret (treat like a password)
* If compromised, rotate the URL from the alert page — the old code stops working immediately
* The JSON payload you send becomes `{{variable}}` fields for your notification template

## Payload Customization

When you send data to Dashtray, it becomes available as variables in your template.

**Example payload from Stripe:**

```json theme={null}
{
  "type": "charge.succeeded",
  "data": {
    "object": {
      "amount": 10000,
      "currency": "usd",
      "customer_email": "user@example.com"
    }
  }
}
```

**Use in template:**

```
Title: "💳 Payment Received"
Body: "${{data.object.amount}} {{data.object.currency}}"

Result: "💳 Payment Received - $100 usd"
```

## Security

### Keep URLs Secret

Treat webhook URLs like passwords. Anyone with your URL can send notifications to your phone.

**Don't:**

* Commit to GitHub
* Post in public channels
* Share unnecessarily

**Do:**

* Store in environment variables
* Use secrets manager
* Rotate if compromised

### Protect Your Webhook URL

The short code is the only credential — anyone with the URL can send notifications to your phone. If a URL leaks, **rotate it** from the alert's webhook settings immediately. Old URLs return 404 after rotation.

## Troubleshooting

### Webhook not triggering

1. Check webhook URL is correct (copy-paste from Dashtray)
2. Verify events are enabled in the service
3. Trigger the event manually
4. Check service's webhook logs

### Webhook triggering but no notification

1. Check template is configured (should say "Configured ✓")
2. Try manually testing the webhook
3. Check if you're in quiet hours — held events arrive in one digest when the window ends (check history to confirm the event was received)
4. Verify alert is active (toggle switch is ON)

### Wrong data in notification

1. Check payload structure matches your template
2. Use correct variable names with {{}}
3. Test with a sample payload
4. Check data path (use dot notation for nested data)

## Rate Limiting

Each alert has a rate limit: **60 requests per minute**

If you exceed this:

* Requests are **rejected** with `429 Rate limit exceeded` — they are not queued
* The service you connected should retry on its own schedule
* Sustained floods (500+/min) **auto-pause the alert**; re-enable it from the app

For high-volume services, consider:

* Multiple alerts with different triggers
* Filtering at the source
* Batch notifications

There is also a global ingestion cap that bounds unauthenticated traffic — malformed URLs (404s) count against abuse monitoring but never hit the database.

## Best Practices

✅ **Do:**

* Use descriptive alert names
* Test webhooks before going live
* Monitor webhook delivery in history
* Set appropriate frequency
* Use template variables for rich data

❌ **Don't:**

* Send every possible event (creates notification overload)
* Share webhook URLs publicly
* Hardcode URLs in code

## Examples by Industry

### E-commerce

* New order received
* Payment failed
* Shipment tracking
* Return request

### SaaS

* Subscription upgraded/downgraded
* Account created
* Payment declined
* Usage threshold reached

### Development

* Build passed/failed
* Deployment complete
* Error rate spike
* Code review requested

### Monitoring

* Alert triggered
* Metric threshold reached
* Service down
* Performance issue

## Support

Need help?

* Check [FAQ](/resources/faq)
* Review [Troubleshooting](/guides/troubleshooting)
* Report issues on [GitHub](https://github.com/bhupeshpradhan/dashtray)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.