Skip to content

Webhooks

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.

A basic webhook configuration looks like this:

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:

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:

{
  "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:

{
  "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"
  }
}