Webhooks

Pro Custodibus can push several different types of events to your own systems over webhooks. When an event of a matching type is generated in Pro Custodibus, Pro Custodibus will queue the event, and every few minutes, POST a JSON list of queued events to your system at the URL and with the HTTP headers you’ve configured.

If Pro Custodibus receives a non-2XX response from a webhook POST, it will re-try the same POST every few minutes until it receives a 2XX response.

Add

Follow these steps to add a new webhook:

Click the Admin link in the app header.
Click the Webhooks link in the Administration panel.
Click the “plus” icon on the right side of the Webhooks panel.
Configure the following fields, then click the Add button to submit the form:

Type

Event type. See the Types section for details of each type.

State

“Active” or “Inactive”. Pause the webhook by setting it to “Inactive”; unpause it by setting it to “Active”.

URL

Full URL of the webhook endpoint that Pro Custodibus will POST HTTP requests to, such as https://example.com/webhooks/123.

Headers

Optional list of HTTP headers Pro Custodibus will include when POSTing HTTP requests. Put one header on each line, like the following:

Authorization: Bearer 123
X-Foo: bar & baz

Extra Fields

Optional list of extra fields to add to the JSON body of each event when POSTed. Put one field on each line, like the following:

source: Pro Custodibus
tags: env:prod,cluster:vpn

Max Events Per Request

Maximum number of events to batch into a single POST HTTP request.

User

For alert-type events only, the user whose alerts should be sent by webhook (the user’s alerts will also be sent to the user over email or SMS as usual, if that user has such contact methods configured to receive security alerts).

Types

Alerts: The same alert events displayed on the Alerts page in the UI.
Endpoint Stats: The raw feed of WireGuard handshake events, with endpoint IPs and bytes sent/received (the same data used by various charts and the endpoint Activity panel).
Log Authn: Events related to Pro Custodibus authentication (similar to the Recent Sessions panel on user pages, but not fully exposed anywhere in the UI).
Log Changes: The WireGuard configuration changes listed in the Changes panels on the dashboard and other pages (WireGuard endpoint IP address changes, keypair and preshared-key changes, endpoints added and removed, etc).

Alerts

The same alert events displayed on the Alerts page in the UI.

Example:

[
   {
     "attributes": {
       "created": "2021-10-25T18:35:22Z",
       "danger": 7,
       "params": {
         "country": "US",
         "country_name": "United States",
         "days": 45,
         "host": "Mailserver",
         "host_pub": "FgepD86z1Jo",
         "ip": "34.220.154.2",
         "peer": "CI",
         "peer_pub": "j9CwNyPm7Q8"
       },
       "suppress_until": "2021-10-26T18:35:21Z",
       "type": "endpoint_ip_first_use_country",
       "updated": "2021-10-25T18:35:22Z"
     },
     "id": "PXT2iiA88At",
     "type": "alerts"
   },
   ...
]

Endpoint Stats

The raw feed of WireGuard handshake events, with endpoint IPs and bytes sent/received (the same data used by various charts and the endpoint Activity panel).

Example:

[
   {
     "attributes": {
       "created": "2021-10-24T02:05:58Z",
       "handshake": "2021-10-24T02:05:07Z",
       "ip": "45.62.209.2",
       "port": 51824,
       "rx_delta": 748,
       "rx_total": 31591436,
       "tx_delta": 772,
       "tx_total": 70276620
     },
     "id": "GH468jtejFr",
     "relationships": {
       "endpoint": {
         "data": [
           {
             "id": "CtfsGB3cABY",
             "type": "endpoints"
           }
         ]
       }
     },
     "type": "endpoint_stats"
   },
   ...
]

Log Authn

Events related to Pro Custodibus authentication (similar to the Recent Sessions panel on user pages, but not fully exposed anywhere in the UI).

Example:

[
   {
     "attributes": {
       "created": "2021-10-24T05:53:11Z",
       "errors": [],
       "ip": "203.33.186.18",
       "status": "ok",
       "type": "X-Custos",
       "url": "/sessions",
       "verifications": [
         "password",
         "user"
       ]
     },
     "id": "6nRLYcXc4KV",
     "relationships": {
       "user": {
         "data": [
           {
             "id": "3tjDGN2gXpT",
             "type": "users"
           }
         ]
       }
     },
     "type": "log_authn"
   },
   ...
]

Log Changes

The WireGuard configuration changes listed in the Changes panels on the dashboard and other pages (WireGuard endpoint IP address changes, keypair and preshared-key changes, endpoints added and removed, etc).

Example:

[
   {
     "attributes": {
       "created": "2021-10-25T19:13:55Z",
       "field": "ip",
       "id": "PykHtrVmLHs",
       "new_value": "52.33.87.203",
       "old_value": "34.219.61.181",
       "type": "endpoints"
     },
     "id": "WKVdbyruaVr",
     "relationships": {
       "user": {
         "data": [
           {
             "id": "NZ1Gq4fs3sp",
             "type": "users"
           }
         ]
       }
     },
     "type": "log_changes"
   },
   ...
]