mirror of https://github.com/h44z/wg-portal.git
86 lines
2.9 KiB
Markdown
86 lines
2.9 KiB
Markdown
|
|
Webhooks allow WireGuard Portal to notify external services about events such as user creation, device changes, or configuration updates. This enables integration with other systems and automation workflows.
|
|
|
|
When webhooks are configured and a specified event occurs, WireGuard Portal sends an HTTP **POST** request to the configured webhook URL.
|
|
The payload contains event-specific data in JSON format.
|
|
|
|
## Configuration
|
|
|
|
All available configuration options for webhooks can be found in the [configuration overview](../configuration/overview.md#webhook).
|
|
|
|
A basic webhook configuration looks like this:
|
|
|
|
```yaml
|
|
webhook:
|
|
url: https://your-service.example.com/webhook
|
|
```
|
|
|
|
### Security
|
|
|
|
Webhooks can be secured by using a shared secret. This secret is included in the `Authorization` header of the webhook request, allowing your service to verify the authenticity of the request.
|
|
You can set the shared secret in the webhook configuration:
|
|
|
|
```yaml
|
|
webhook:
|
|
url: https://your-service.example.com/webhook
|
|
secret: "Basic dXNlcm5hbWU6cGFzc3dvcmQ="
|
|
```
|
|
|
|
You should also make sure that your webhook endpoint is secured with HTTPS to prevent eavesdropping and tampering.
|
|
|
|
## Available Events
|
|
|
|
WireGuard Portal supports various events that can trigger webhooks. The following events are available:
|
|
|
|
- `create`: Triggered when a new entity is created.
|
|
- `update`: Triggered when an existing entity is updated.
|
|
- `delete`: Triggered when an entity is deleted.
|
|
- `connect`: Triggered when a user connects to the VPN.
|
|
- `disconnect`: Triggered when a user disconnects from the VPN.
|
|
|
|
The following entity types can trigger webhooks:
|
|
|
|
- `user`: When a WireGuard Portal user is created, updated, or deleted.
|
|
- `peer`: When a peer is created, updated, or deleted. This entity can also trigger `connect` and `disconnect` events.
|
|
- `interface`: When a device is created, updated, or deleted.
|
|
|
|
## Payload Structure
|
|
|
|
All webhook events send a JSON payload containing relevant data. The structure of the payload depends on the event type and entity involved.
|
|
A common shell structure for webhook payloads is as follows:
|
|
|
|
```json
|
|
{
|
|
"event": "create",
|
|
"entity": "user",
|
|
"identifier": "the-user-identifier",
|
|
"payload": {
|
|
// The payload of the event, e.g. peer data.
|
|
// Check the API documentation for the exact structure.
|
|
}
|
|
}
|
|
```
|
|
|
|
|
|
### Example Payload
|
|
|
|
The following payload is an example of a webhook event when a peer connects to the VPN:
|
|
|
|
```json
|
|
{
|
|
"event": "connect",
|
|
"entity": "peer",
|
|
"identifier": "Fb5TaziAs1WrPBjC/MFbWsIelVXvi0hDKZ3YQM9wmU8=",
|
|
"payload": {
|
|
"PeerId": "Fb5TaziAs1WrPBjC/MFbWsIelVXvi0hDKZ3YQM9wmU8=",
|
|
"IsConnected": true,
|
|
"IsPingable": false,
|
|
"LastPing": null,
|
|
"BytesReceived": 1860,
|
|
"BytesTransmitted": 10824,
|
|
"LastHandshake": "2025-06-26T23:04:33.325216659+02:00",
|
|
"Endpoint": "10.55.66.77:33874",
|
|
"LastSessionStart": "2025-06-26T22:50:40.10221606+02:00"
|
|
}
|
|
}
|
|
``` |