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

# Creating Webhooks

This guide walks you through creating a webhook endpoint to receive real-time notifications from your YAPL workspace.

## Prerequisites

- You must be a **workspace owner**
- Your workspace must be on a **Professional** or **Trial** plan
- You need the URL of the service that will receive webhook deliveries

## Creating Your First Webhook

1. Navigate to **Settings > Webhooks**
2. Click **Create Webhook**
3. Fill in the endpoint details:
   - **Name** — A descriptive name (e.g., "Slack Project Updates")
   - **URL** — The HTTPS endpoint that will receive deliveries
   - **Description** — Optional notes about what this webhook does
4. Click **Save**
5. **Copy the signing secret** — This is shown only once and is required to verify signatures

### Important: Save Your Secret

When you create a webhook, YAPL generates a unique signing secret. This secret is displayed **only once** immediately after creation. Copy it and store it securely — you'll need it to [verify webhook signatures](/docs/user-guides/webhooks/verifying-signatures).

If you lose your secret, you'll need to delete the webhook and create a new one.

## Endpoint URL Requirements

- Must be a valid HTTPS URL (HTTP is allowed only in development environments)
- Must be publicly accessible from the internet
- Must respond within 10 seconds
- Private IP addresses and internal networks are blocked for security

## Configuring Event Types

By default, a new webhook receives **all events**. To limit which events trigger deliveries:

1. Open the webhook's create or edit dialog
2. Turn off **All events**
3. Tick the event types you want to receive, then save

For example, if you only want project notifications, select the project events and leave the others unchecked. See [Event Types](/docs/user-guides/webhooks/event-types) for the full list.

## Custom Headers

You can add custom HTTP headers that YAPL will include with every delivery. This is useful for:

- **Authentication** — Add an `Authorization` header for your receiving service
- **Routing** — Add custom headers to route deliveries within your infrastructure
- **Identification** — Add headers to distinguish YAPL deliveries from other sources

To add custom headers:

1. Open the Create or Edit webhook dialog
2. Click **Add Header**
3. Enter the header name and value
4. Add more headers as needed

## Editing a Webhook

1. Navigate to **Settings > Webhooks**
2. Find the endpoint in the list
3. Click the menu icon and select **Edit**
4. Make your changes
5. Click **Save**

You can update the name, URL, description, event types, custom headers, and active status. The signing secret cannot be changed — create a new webhook if you need a new secret.

## Enabling and Disabling

To temporarily stop deliveries without deleting the webhook:

1. Edit the webhook
2. Toggle the **Active** switch off
3. Save

Disabled webhooks remain in your list but won't receive any deliveries. Toggle the switch back on to resume.

## Testing a Webhook

Before relying on a webhook for important notifications, test it:

1. Navigate to **Settings > Webhooks**
2. Click the menu icon on the endpoint
3. Select **Test**
4. YAPL sends a test payload to your endpoint
5. Check the result — success or failure with details

The test delivery uses a sample payload and is recorded in the [delivery logs](/docs/user-guides/webhooks/delivery-logs).

## Deleting a Webhook

1. Navigate to **Settings > Webhooks**
2. Click the menu icon on the endpoint
3. Select **Delete**
4. Confirm the deletion

Deleting a webhook is permanent. All delivery logs for that endpoint are also removed. If you might need the webhook again, consider disabling it instead.

## Endpoint Limits

Each workspace can have up to **10 webhook endpoints**. This limit includes both active and disabled endpoints.

If you need more endpoints, consider consolidating — you can create a single endpoint that receives all events and routes them within your own service.

## Common Configurations

### Slack Incoming Webhook

1. In Slack, create an [Incoming Webhook](https://api.slack.com/messaging/webhooks)
2. Copy the webhook URL
3. Create a YAPL webhook with that URL
4. Select the events you want posted to your Slack channel

### Discord Webhook

1. In Discord, go to Channel Settings > Integrations > Webhooks
2. Create a new webhook and copy the URL
3. Append `/slack` to the Discord webhook URL (Discord supports Slack-compatible format)
4. Create a YAPL webhook with that URL

### Zapier / Make / n8n

1. Create a new Zap, Scenario, or Workflow with a **Webhook** trigger
2. Copy the webhook URL provided by the automation platform
3. Create a YAPL webhook with that URL
4. Build your automation using the incoming event data

## Troubleshooting

### Webhook not receiving deliveries

- Verify the endpoint is **Active** (not disabled)
- Check the URL is publicly accessible
- Ensure your server responds within 10 seconds
- Review [delivery logs](/docs/user-guides/webhooks/delivery-logs) for error details

### "URL not allowed" error

- YAPL blocks private IP addresses (10.x.x.x, 192.168.x.x, etc.)
- YAPL blocks localhost and metadata endpoints
- Use a publicly accessible URL

### Secret lost

- Secrets are shown only once at creation time
- Delete the webhook and create a new one
- Update your receiving service with the new secret

## Related Topics

- [Event Types](/docs/user-guides/webhooks/event-types) — Events that trigger deliveries
- [Delivery Logs](/docs/user-guides/webhooks/delivery-logs) — Monitor delivery status
- [Verifying Signatures](/docs/user-guides/webhooks/verifying-signatures) — Secure your endpoint