# Webhooks

> Subscribe an endpoint to platform events and verify signed deliveries.

Source: https://gheima.ma/docs/webhooks

Outgoing webhooks send platform events to an endpoint you control, so external systems can react to what happens on Gheima. Manage them on the Webhooks page or through the API. Only admins can manage webhooks.

### Create a webhook

POST a URL and the events you want. Pass an empty events list ([]) to subscribe to every event. The signing secret is returned once. Store it somewhere safe.

```bash
curl -X POST https://api.gheima.ma/v1/webhooks \
  -H "Authorization: Bearer gh_xxxxx" -H "content-type: application/json" \
  -d '{"url":"https://example.com/hook","events":["DEPLOYMENT_CREATED"]}'
```

### Events

- DEPLOYMENT_CREATED: a deployment started. Delivered as deployment.created.
- DEPLOYMENT_SUCCEEDED and DEPLOYMENT_FAILED: a deployment went live or failed, previews and rollbacks included (a preview carries preview: true). Delivered as deployment.succeeded and deployment.failed. A cancelled or skipped deployment sends neither.
- SERVICE_CREATED and SERVICE_DELETED: a service was created or deleted. Delivered as service.created and service.deleted.
- DATABASE_CREATED: a database was provisioned. Delivered as database.created.
- PING: the test event. Delivered as ping.

### Verify deliveries

Each delivery is a JSON body { event, data, timestamp } with an x-gheima-event header and an x-gheima-signature header (sha256=HMAC of the raw body using your secret). Verify the signature before trusting the payload. Send a sample delivery any time:

```bash
curl -X POST https://api.gheima.ma/v1/webhooks/<id>/test \
  -H "Authorization: Bearer gh_xxxxx"
```

Sends a ping event to your endpoint.

> Result: Your systems react to Gheima events in real time, with signed payloads you can verify.

---

All docs: https://gheima.ma/docs.md