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

# How to Configure Webhooks

> Set up webhook endpoints to receive real-time notifications when events occur in your PlaneConnection workspace.

This guide explains how to create webhook endpoints that receive real-time HTTP notifications when events happen in your PlaneConnection workspace.

<Warning>
  This feature requires **administrator** or **workspace owner** permissions. Changes made here
  affect all users in your workspace.
</Warning>

<Info>
  **Who should read this:** Workspace administrators and developers building integrations that need
  real-time event data from PlaneConnection.

  **Prerequisites:** Admin or Account Owner role. A publicly accessible HTTPS endpoint to receive
  webhook payloads.
</Info>

## How webhooks work

When an event occurs in your workspace (e.g., a trip is created, a safety report is submitted, or an invoice is paid), PlaneConnection sends an HTTP POST request to your configured endpoint with a JSON payload describing the event.

Your server processes the payload and responds with a `200` status code to acknowledge receipt. If your endpoint does not respond or returns an error, PlaneConnection retries the delivery with exponential backoff.

## Create a webhook endpoint

<Steps>
  ### Navigate to webhook settings

  Go to **Settings > Webhooks**. This page lists all configured webhook endpoints.

  ### Click New Webhook

  Click the **New Webhook** button.

  ### Configure the endpoint

  | Field           | Description                                                                                                        |
  | --------------- | ------------------------------------------------------------------------------------------------------------------ |
  | **URL**         | The HTTPS endpoint that will receive webhook payloads.                                                             |
  | **Description** | A descriptive label (e.g., "Slack trip notifications" or "CRM sync").                                              |
  | **Events**      | Select which event types trigger this webhook. You can subscribe to all events or specific types.                  |
  | **Secret**      | A signing secret used to verify that payloads come from PlaneConnection. Auto-generated, but you can set your own. |

  ### Save and test

  Click **Save**. Use the **Send Test** button to send a test payload to your endpoint and verify it receives the data correctly.
</Steps>

<Warning>
  Webhook endpoints must use HTTPS. HTTP endpoints are rejected for security reasons. Self-signed
  certificates are not supported.
</Warning>

## Verify webhook signatures

Every webhook payload includes a signature header (`X-PlaneConnection-Signature`) that you should verify to confirm the payload was sent by PlaneConnection and was not tampered with.

The signature is an HMAC-SHA256 hash of the request body using your webhook's signing secret:

```
HMAC-SHA256(webhook_secret, request_body)
```

Compare the computed hash against the `X-PlaneConnection-Signature` header value. Reject the payload if they do not match.

## Manage webhook endpoints

### Edit an endpoint

1. Navigate to **Settings > Webhooks**.
2. Click the webhook you want to edit.
3. Update the URL, events, or description.
4. Click **Save**.

### Disable an endpoint

Toggle the **Active** switch to temporarily stop deliveries without deleting the endpoint configuration.

### Delete an endpoint

Click **Delete** on the webhook detail page. This permanently removes the endpoint and stops all deliveries.

### View delivery history

On the webhook detail page, the **Deliveries** tab shows recent delivery attempts with:

* Timestamp
* Event type
* HTTP response code
* Response time
* Payload preview

Failed deliveries are highlighted in red. Click a delivery to see the full request and response details.

## Retry behavior

| Attempt | Delay      | Description                |
| :-----: | ---------- | -------------------------- |
|    1    | Immediate  | First delivery attempt.    |
|    2    | 1 minute   | First retry after failure. |
|    3    | 5 minutes  | Second retry.              |
|    4    | 30 minutes | Third retry.               |
|    5    | 2 hours    | Final retry attempt.       |

After five failed attempts, the delivery is marked as **Failed** and no further retries are attempted. You can manually retry from the delivery history.

## Related

<CardGroup cols={2}>
  <Card title="Webhook Events Reference" href="/en/reference/webhook-events">
    All event types and payload schemas.
  </Card>

  <Card title="API Webhooks" href="/en/reference/api/webhooks">
    API-level webhook documentation.
  </Card>

  <Card title="Manage API Keys" href="/en/how-to/admin/manage-api-keys">
    Create API keys for programmatic access.
  </Card>

  <Card title="Set Up Integrations" href="/en/how-to/admin/set-up-integrations">
    Connect third-party tools to your workspace.
  </Card>
</CardGroup>