3 Webhooks
Anton Nesterov edited this page 2026-11-01 20:55:38 +01:00

Webhooks

The webhooks engine is responsible for executing requests for collection triggers and cron jobs.

  • A webhook can send Bearer with JWT payload signed by a VSKI instance.
  • Currently webhooks do not support sending files.
  • Workflows use a separate inbound endpoint to receive events and are not to be confused with collection and cron outbound webhooks.

API Endpoints

Method Endpoint Description
GET /api/webhooks/logs List webhook logs
GET /api/webhooks/logs?collection=name Filter by collection
GET /api/webhooks/logs?status=failed Filter by status
GET /api/webhooks/logs?page=1&perPage=50 Paginate results

Webhooks are configured via collection management:

Method Endpoint Description
POST /api/collections Create collection with triggers
PATCH /api/collections/:name Update collection triggers

From the command line: vski webhooks logs, vski webhooks logs --status failed, vski webhooks trigger <id>.

Security Best Practices

  1. Use HTTPS: always use HTTPS URLs for webhooks
  2. Secure tokens: store API tokens in environment variables
  3. Verify signatures: implement signature verification on receiving endpoints (future feature)
  4. Rate limiting: implement rate limiting on webhook endpoints
  5. Validate payloads: always validate incoming webhook data
  6. Use authentication: include authentication headers in triggers
  7. Monitor logs: regularly check webhook logs for failures
  8. Test endpoints: verify webhook endpoints work before production

Testing Webhooks

Using Webhook Testing Services

Use webhook testing services during development:

# vski/default/collections.yaml: collection with a test webhook URL
version: 1
database: default

collections:
  test_collection:
    type: base
    fields:
      - {name: data, type: text, required: true}
    options:
      triggers:
        - action: create
          url: https://webhook.site/your-unique-id
          method: POST
# Create a test record to trigger the webhook,
# then check webhook.site to see the payload
await client.collection("test_collection").create({"data": "Test data"})

Manual Testing

await client.collection("notifications").create(
    {"title": "Test Notification", "message": "This is a test", "status": "active"}
)

logs = await client.webhook_logs.list(collection="notifications", page=1, per_page=10)
print(logs)