Document webhooks

Author: jbrooksuk

mint.json

@@ -75,6 +75,7 @@
         "v3.x/guide/schedules",
         "v3.x/guide/metrics",
         "v3.x/guide/subscribers",
+        "v3.x/guide/webhooks",
         "v3.x/guide/dashboard"
       ]
     }, {

v3.x/guide/webhooks.mdx

@@ -0,0 +1,98 @@
+---
+title: Webhooks
+description: Learn how to use webhooks in Cachet.
+icon: plug
+---
+
+Cachet can be configured to notify external services of various events using webhooks. Webhooks are HTTP callbacks
+that are triggered by specific events. When an event occurs, Cachet sends an HTTP `POST` request to the configured URL
+with a JSON payload containing information about the event. Webhooks consist of:
+
+- **Payload URL**: The URL that Cachet will send the webhook to.
+- **Secret**: A secret key that is used to sign the webhook payload. This can be used to verify that the payload was sent by
+  Cachet and not a third party.
+- **Events**: The events that will trigger the webhook.
+
+The Cachet dashboard provides a user-friendly interface for managing webhooks. You can add, edit, and delete webhooks
+from the "Manage Webhooks" page.
+
+### Supported Events
+
+Cachet currently supports the following events:
+
+- `component_created`
+- `component_updated`
+- `component_deleted`
+- `component_status_changed`
+- `incident_created`
+- `incident_updated`
+- `incident_deleted`
+- `metric_created`
+- `metric_updated`
+- `metric_deleted`
+- `metric_point_created`
+- `metric_point_deleted`
+- `subsciber_created`
+- `subscriber_unsubscribed`
+- `subscribed_verified`
+
+<Tip>
+    Cachet may add more events in the future. Check the latest documentation for the most up-to-date list of supported events.
+</Tip>
+
+## Receiving Webhooks
+
+### User Agent
+
+Cachet will send a `User-Agent` header with the request. The value of the `User-Agent` header will be:
+
+```
+Cachet/3.0 Webhook (+https://docs.cachethq.io)
+```
+
+### Payload
+
+The payload sent by Cachet will contain information about the event that triggered the webhook. The payload will be a JSON
+object with the following structure:
+
+```json
+{
+  "event": "incident_updated",
+  "body": {
+    "id": 3,
+    "component_id": null,
+    "name": "Test",
+    "status": 2,
+    "message": "sdsd",
+    "created_at": "2025-01-09T13:44:30.000000Z",
+    "updated_at": "2025-01-09T13:49:54.000000Z",
+    "deleted_at": null,
+    "visible": 1,
+    "stickied": false,
+    "occurred_at": null,
+    "user_id": 1,
+    "notifications": false,
+    "guid": "19801cb7-883c-490e-8569-e552b013b2cc",
+    "external_provider": null,
+    "external_id": null
+  }
+}
+```
+
+## Signature Verification
+
+When a webhook is triggered, Cachet will send a `Signature` header with the request. This header is used to verify that
+data was not tampered with during transit. The signature is computed by hashing the request body with the secret key and
+comparing it to the value in the `Signature` header.
+
+### Verifying Signatures
+
+```php
+$configuredSigningSecret = 'your-signing-secret';
+
+$computedSignature = hash_hmac('sha256', $request->getContent(), $configuredSigningSecret);
+
+if ($computedSignature !== $request->header('Signature')) {
+    abort(500);
+}
+```