mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-07-27 20:29:10 +00:00
Anso
ffabfd1c39
Update 11 doc pages with accurate content and capture 14 fresh screenshots. Remove JWT_SECRET from configuration (auto-generated), fix editor container actions, add missing Settings sections, update Features Overview, and add remote alerts documentation.
132 lines
4.1 KiB
Plaintext
132 lines
4.1 KiB
Plaintext
---
|
|
title: Webhooks
|
|
description: Trigger stack actions from CI/CD pipelines via HTTP webhooks with HMAC signature authentication.
|
|
---
|
|
|
|
<Note>
|
|
Webhooks require a Sencho Pro license.
|
|
</Note>
|
|
|
|
Sencho webhooks let external systems trigger stack actions over HTTP. The typical use case: your CI pipeline builds a new image, then calls a Sencho webhook to deploy the updated stack - no manual intervention required.
|
|
|
|
## How it works
|
|
|
|
1. You create a webhook in **Settings → Webhooks**, targeting a specific stack and action
|
|
2. Sencho generates a unique secret for HMAC-SHA256 signature validation
|
|
3. Your CI/CD system sends a `POST` request to the trigger URL with the correct signature
|
|
4. Sencho validates the signature and executes the action asynchronously
|
|
|
|
## Creating a webhook
|
|
|
|
<Frame>
|
|
<img src="/images/webhooks/webhooks-settings.png" alt="Webhooks settings panel" />
|
|
</Frame>
|
|
|
|
Open **Settings → Webhooks** and click **Create Webhook**. Fill in:
|
|
|
|
| Field | Description |
|
|
|-------|-------------|
|
|
| **Name** | A display name (e.g. "Deploy on push") |
|
|
| **Stack** | The target stack to act on |
|
|
| **Action** | One of: `deploy`, `restart`, `stop`, `start`, `pull` |
|
|
|
|
After creation, Sencho shows the webhook secret **once**. Copy it immediately - it cannot be retrieved later.
|
|
|
|
### Actions explained
|
|
|
|
| Action | What it does |
|
|
|--------|-------------|
|
|
| **Deploy** | Runs `docker compose down` then `docker compose up -d` (full redeploy) |
|
|
| **Restart** | Runs `docker compose restart` |
|
|
| **Stop** | Runs `docker compose stop` |
|
|
| **Start** | Runs `docker compose start` |
|
|
| **Pull** | Pulls latest images and recreates changed containers |
|
|
|
|
## Triggering a webhook
|
|
|
|
Send a POST request to the trigger URL with an HMAC-SHA256 signature:
|
|
|
|
```
|
|
POST /api/webhooks/{id}/trigger
|
|
Content-Type: application/json
|
|
X-Webhook-Signature: sha256={hmac}
|
|
```
|
|
|
|
The signature is computed as `HMAC-SHA256(request_body, webhook_secret)` and sent in the `X-Webhook-Signature` header with a `sha256=` prefix.
|
|
|
|
### Example with curl
|
|
|
|
```bash
|
|
SECRET="your-webhook-secret"
|
|
BODY='{}'
|
|
SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | cut -d' ' -f2)
|
|
|
|
curl -X POST https://your-sencho.com/api/webhooks/3/trigger \
|
|
-H "Content-Type: application/json" \
|
|
-H "X-Webhook-Signature: sha256=$SIGNATURE" \
|
|
-d "$BODY"
|
|
```
|
|
|
|
### Overriding the action
|
|
|
|
By default, the webhook executes the action configured at creation time. You can override it per-request by including an `action` field in the body:
|
|
|
|
```json
|
|
{ "action": "restart" }
|
|
```
|
|
|
|
### Response
|
|
|
|
A successful trigger returns `202 Accepted` immediately. The action executes asynchronously in the background.
|
|
|
|
```json
|
|
{ "message": "Webhook accepted", "action": "deploy" }
|
|
```
|
|
|
|
## CI/CD integration examples
|
|
|
|
### GitHub Actions
|
|
|
|
```yaml
|
|
- name: Deploy via Sencho
|
|
run: |
|
|
BODY='{}'
|
|
SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "${{ secrets.SENCHO_WEBHOOK_SECRET }}" | cut -d' ' -f2)
|
|
curl -X POST "${{ secrets.SENCHO_URL }}/api/webhooks/${{ secrets.SENCHO_WEBHOOK_ID }}/trigger" \
|
|
-H "Content-Type: application/json" \
|
|
-H "X-Webhook-Signature: sha256=$SIGNATURE" \
|
|
-d "$BODY"
|
|
```
|
|
|
|
### GitLab CI
|
|
|
|
```yaml
|
|
deploy:
|
|
stage: deploy
|
|
script:
|
|
- BODY='{}'
|
|
- SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SENCHO_WEBHOOK_SECRET" | cut -d' ' -f2)
|
|
- 'curl -X POST "$SENCHO_URL/api/webhooks/$SENCHO_WEBHOOK_ID/trigger"
|
|
-H "Content-Type: application/json"
|
|
-H "X-Webhook-Signature: sha256=$SIGNATURE"
|
|
-d "$BODY"'
|
|
```
|
|
|
|
## Execution history
|
|
|
|
Each webhook tracks its last 100 executions. Click **Recent executions** on any webhook row to see:
|
|
|
|
- Status (success/failure)
|
|
- Action performed
|
|
- Execution time
|
|
- Duration
|
|
- Error message (if failed)
|
|
|
|
## Security
|
|
|
|
- Webhook secrets are 64-character hex strings generated with `crypto.randomBytes(32)`
|
|
- Signature validation uses `crypto.timingSafeEqual` to prevent timing attacks
|
|
- Secrets are shown only once at creation - API responses return masked values
|
|
- Webhook trigger endpoints are public (no session cookie required) but protected by HMAC signature validation
|
|
- Each webhook targets a single stack - there is no way to execute arbitrary commands
|