# Webhooks (https://yapl.app/en/docs/user-guides/webhooks)

# Webhooks

Webhooks let YAPL send real-time notifications to external services whenever something happens in your workspace. When a project is created, a task is updated, or a team member is added, YAPL can instantly notify tools like Slack, Discord, Zapier, Make, n8n, or your own custom services.

## How Webhooks Work

When an event occurs in your workspace, YAPL:

1. Checks which webhook endpoints are configured for that event type
2. Builds a JSON payload with the event details
3. Sends an HTTP POST request to each matching endpoint
4. Logs the delivery result (success or failure)
5. Retries failed deliveries automatically

## What You Can Do With Webhooks

- **Slack/Discord notifications** — Get a message in your team channel when a project status changes
- **Automation platforms** — Trigger Zapier, Make, or n8n workflows from YAPL events
- **Custom dashboards** — Feed project updates into your internal tools
- **Audit trails** — Send event data to external logging services
- **Email alerts** — Trigger email notifications through services like SendGrid or Mailgun

## Availability

Webhooks are available on **Professional** and **Trial** plans. Each workspace can have up to **10 webhook endpoints**.

| Plan | Webhooks |
|------|----------|
| Trial | Up to 10 endpoints |
| Basic | Not available |
| Professional | Up to 10 endpoints |

If you're on the Basic plan, you can view and delete existing webhooks but cannot create new ones or edit existing endpoints. [Upgrade your plan](/docs/user-guides/billing/upgrading-plan) to enable webhooks.

## In This Section

### Setup
- **[Creating Webhooks](/docs/user-guides/webhooks/creating-webhooks)** — Create and configure webhook endpoints

### Reference
- **[Event Types](/docs/user-guides/webhooks/event-types)** — All events that can trigger webhook deliveries

### Monitoring
- **[Delivery Logs](/docs/user-guides/webhooks/delivery-logs)** — Track delivery status and troubleshoot failures

### Security
- **[Verifying Signatures](/docs/user-guides/webhooks/verifying-signatures)** — Validate that deliveries came from YAPL

## Quick Reference

| Task | Location |
|------|----------|
| Create a webhook | Settings > Webhooks > Create Webhook |
| Edit a webhook | Settings > Webhooks > [Endpoint] > Edit |
| Delete a webhook | Settings > Webhooks > [Endpoint] > Delete |
| Test a webhook | Settings > Webhooks > [Endpoint] > Test |
| View delivery logs | Settings > Webhooks > [Endpoint] > Deliveries |

## Webhook Payload Format

Every webhook delivery sends a JSON payload with this structure:

```json
{
  "id": "evt_abc123",
  "type": "project.created.v1",
  "timestamp": "2026-03-25T10:30:00.000Z",
  "workspaceId": "ws_xyz789",
  "data": {
    "projectId": "proj_456",
    "projectName": "Office Renovation",
    "status": "planning"
  }
}
```

| Field | Description |
|-------|-------------|
| `id` | Unique event identifier |
| `type` | Event type (see [Event Types](/docs/user-guides/webhooks/event-types)) |
| `timestamp` | When the event occurred (ISO 8601) |
| `workspaceId` | Your workspace identifier |
| `data` | Event-specific details |

## Security

Every delivery includes an HMAC-SHA256 signature in the `X-YAPL-Signature-256` header. Your receiving service should verify this signature to confirm the request came from YAPL. See [Verifying Signatures](/docs/user-guides/webhooks/verifying-signatures) for implementation details.

Sensitive information (passwords, tokens, API keys) is automatically stripped from payloads before delivery.

## Retry Policy

If a delivery fails (network error or non-2xx response), YAPL retries automatically:

| Attempt | Delay |
|---------|-------|
| 1st retry | 30 seconds |
| 2nd retry | 2 minutes |
| 3rd retry | 10 minutes |
| 4th retry | 1 hour |
| 5th retry | 6 hours |

After 5 failed attempts, the delivery is marked as failed. You can view all delivery attempts in the [Delivery Logs](/docs/user-guides/webhooks/delivery-logs).

## Related Topics

- [Subscription Plans](/docs/user-guides/billing/subscription-plans) — Plan comparison and feature availability
- [Upgrading Plan](/docs/user-guides/billing/upgrading-plan) — Enable webhooks by upgrading
- [Workspace Settings](/docs/user-guides/workspaces/workspace-settings) — Other workspace configuration