mirror of
https://github.com/h44z/wg-portal.git
synced 2025-06-28 01:07:03 +00:00
be29abd29a
* add webhook event for peer state change (#444) new event types: connect and disconnect example payload: ```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" } } ``` * add webhook docs (#444)
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"
|
|
}
|
|
}
|
|
``` |