Val Town API and Webhook Examples

This project contains examples of HTTP APIs and webhook handlers implemented in Val Town.

1. simpleApi.ts - A basic API example that demonstrates handling different HTTP methods (GET, POST, PUT, DELETE)
2. todoApi.ts - A RESTful API for a todo application using SQLite for persistence
3. webhookHandler.ts - A webhook handler that can process events from external services

The Simple API demonstrates basic HTTP request handling. You can test it with:

• GET: https://your-val-url.val.run?name=YourName
• POST: Send a JSON body to https://your-val-url.val.run
• PUT: Send a JSON body to https://your-val-url.val.run
• DELETE: https://your-val-url.val.run?id=123

The Todo API provides a complete RESTful interface for managing todo items:

• GET /todos - List all todos
• GET /todos/{id} - Get a specific todo
• POST /todos - Create a new todo (send JSON with title and optional completed fields)
• PUT /todos/{id} - Update a todo (send JSON with fields to update)
• DELETE /todos/{id} - Delete a todo

Example JSON for creating a todo:

{
  "title": "Buy groceries",
  "completed": false
}

The webhook handler processes events from external services. To use it:

1. Set a WEBHOOK_SECRET environment variable in Val Town for security
2. Configure your external service to send webhooks to your Val URL
3. The handler expects:
   • POST requests
   • An x-event-type header or event query parameter
   • A JSON payload
   • Optionally, an x-webhook-signature header for verification

To handle new webhook event types, add a new case to the processWebhook function and create a corresponding handler function.

If you need to modify the database schema in the Todo API:

1. Change the TABLE_NAME constant (e.g., from todos_v1 to todos_v2)
2. Update the initDatabase function with your new schema
3. Update the corresponding CRUD functions to match your schema changes

• Always use environment variables for secrets
• Implement proper signature verification for webhooks
• Consider adding rate limiting for production APIs

You can test your APIs using tools like:

• The Val Town web interface
• cURL from your terminal
• Postman or similar API testing tools
• Simple fetch requests from another Val

Example cURL command:

curl -X POST https://your-val-url.val.run/todos \
  -H "Content-Type: application/json" \
  -d '{"title": "Test todo", "completed": false}'