Testing Webhooks

Test your webhook endpoint before going live.

Test Endpoint

Send a test event to verify your endpoint:

curl -X POST "https://api.kula.ai/v1/webhooks/{id}/test" \
  -H "Authorization: Bearer your_api_token_here"

Response:

{
  "test_id": "test_abc123",
  "status": "pending"
}

Poll Test Status

Check the test result:

curl "https://api.kula.ai/v1/webhooks/{id}/test/test_abc123" \
  -H "Authorization: Bearer your_api_token_here"

Response:

{
  "test_id": "test_abc123",
  "status": "delivered",
  "response_code": 200,
  "response_time_ms": 245
}

Local Development

Using webhook.site

1. Go to webhook.site
2. Copy your unique URL
3. Create a webhook with that URL
4. Send a test event
5. View the payload on webhook.site

Using ngrok

Expose your local server to receive webhooks:

# Terminal 1: Start your server
node server.js  # Listening on port 3000

# Terminal 2: Expose via ngrok
ngrok http 3000

Use the ngrok URL (e.g., https://abc123.ngrok.io/webhooks/kula) as your webhook endpoint.

Test Payload

The test endpoint sends a ping event:

{
  "event": "ping",
  "event_id": "evt_test_abc123",
  "created_at": "2025-01-15T10:30:00Z",
  "account_id": 12345,
  "data": {
    "message": "Webhook test"
  }
}

Verifying Your Handler

Ensure your endpoint:

1. Returns 200 within 10 seconds
2. Verifies the signature
3. Handles the event type
4. Responds before processing (async)

app.post('/webhooks/kula', (req, res) => {
  // Verify signature first
  if (!verifyWebhook(req, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Respond immediately
  res.status(200).send('OK');

  // Process asynchronously
  processWebhookAsync(req.body);
});