Skip to main content

Webhooks

Webhooks notify your server when important events occur. Register a URL, choose the events to subscribe to, and inspect failed deliveries to diagnose issues in development.

info

Webhooks should return 2xx quickly. Do your heavy work asynchronously after acknowledging receipt. Always validate the request (e.g., shared secret/signature) before trusting the payload.

List webhooks​

GET /api/v1/project/{projectId}/webhooks

cURL​

curl -s "$FREEQ_API_URL/api/v1/project/123/webhooks?showDeleted=false" \
  -H "Authorization: Bearer $FREEQ_API_TOKEN"

Create webhook​

POST /api/v1/project/{projectId}/webhooks

cURL​

curl -s -X POST "$FREEQ_API_URL/api/v1/project/123/webhooks" \
  -H "Authorization: Bearer $FREEQ_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/freeq","secret":"shh","events":["membership.updated","transaction.created"]}'

Failed deliveries​

GET /api/v1/project/{projectId}/webhooks/failedDeliveries

cURL​

curl -s "$FREEQ_API_URL/api/v1/project/123/webhooks/failedDeliveries" \
  -H "Authorization: Bearer $FREEQ_API_TOKEN"

Quick start (Express)​

// Minimal webhook receiver
app.post('/webhooks/freeq', express.json({ type: '*/*' }), (req, res) => {
  console.log('Freeq webhook:', { headers: req.headers, body: req.body });
  // TODO: verify signature and handle events
  res.sendStatus(200);
});