Preswald Logopreswald

Webhooks and Events

Receive real-time notifications about events in your Preswald account.

Table of Contents

Overview

Webhooks allow your application to receive real-time notifications when events occur in your Preswald account. Instead of polling our API, you can configure webhook endpoints to receive HTTP POST requests when specific events happen.

Common use cases include:

  • Updating your database when an app is deployed
  • Sending notifications when data processing completes
  • Triggering workflows when users interact with your apps
  • Monitoring app performance and usage

Setup

Creating a Webhook

You can create webhooks through the API or the Preswald dashboard.

POST https://api.preswald.com/v1/webhooks
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "url": "https://your-app.com/webhooks/preswald",
  "events": ["app.deployed", "data.processed"],
  "secret": "your-webhook-secret",
  "active": true
}

Webhook Endpoint Requirements

  • Must be accessible via HTTPS
  • Should respond with a 2xx status code within 30 seconds
  • Should be idempotent (safe to retry)
  • Should validate the webhook signature

Event Types

Preswald supports the following webhook events:

EventDescription
app.createdA new app was created
app.updatedAn app was modified
app.deployedAn app was deployed
app.deletedAn app was deleted
data.processedData processing completed
user.interactionUser interacted with an app

Payload Format

All webhook payloads follow a consistent format:

{
  "id": "evt_1234567890",
  "type": "app.deployed",
  "created": "2023-06-01T12:00:00Z",
  "data": {
    "object": {
      "id": "app_123456",
      "title": "Sales Dashboard",
      "deployment": {
        "id": "dep_789012",
        "url": "https://app-123456.preswald.app",
        "status": "live",
        "deployed_at": "2023-06-01T12:00:00Z"
      }
    }
  },
  "account": {
    "id": "acc_345678",
    "name": "Acme Corp"
  }
}

Example: User Interaction Event

{
  "id": "evt_2345678901",
  "type": "user.interaction",
  "created": "2023-06-01T12:05:00Z",
  "data": {
    "object": {
      "app_id": "app_123456",
      "user_id": "user_456789",
      "interaction_type": "chart_click",
      "chart_id": "chart_001",
      "data_point": {
        "x": "2023-05",
        "y": 15000,
        "category": "sales"
      }
    }
  }
}

Security

Preswald signs webhook payloads with a secret key to ensure they're authentic.

Verifying Signatures

import hmac
import hashlib

def verify_webhook_signature(payload, signature, secret):
    """Verify the webhook signature"""
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    # Compare signatures securely
    return hmac.compare_digest(
        f"sha256={expected_signature}",
        signature
    )

# Usage in your webhook handler
def handle_webhook(request):
    payload = request.body
    signature = request.headers.get('X-Preswald-Signature')
    secret = 'your-webhook-secret'
    
    if not verify_webhook_signature(payload, signature, secret):
        return HttpResponse(status=401)
    
    # Process the webhook...

Testing

You can test your webhook endpoints using the Preswald CLI or dashboard.

Using the CLI

# Install the Preswald CLI
npm install -g @preswald/cli

# Test a webhook endpoint
preswald webhooks test \
  --endpoint https://your-app.com/webhooks/preswald \
  --event app.deployed \
  --app-id app_123456

Local Development

For local development, you can use tools like ngrok to expose your local server to the internet:

# Install ngrok
npm install -g ngrok

# Expose your local server
ngrok http 3000

# Use the ngrok URL for your webhook endpoint
# https://abc123.ngrok.io/webhooks/preswald

Webhook Logs

Monitor webhook delivery attempts in your Preswald dashboard under Settings → Webhooks. You can see delivery status, response codes, and retry attempts.