Webhooks API

Create and manage webhooks programmatically to receive real-time notifications.

List Webhooks

GET/v1/webhooks

{
  "success": true,
  "data": {
    "webhooks": [
      {
        "webhook_id": "wh_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
        "url": "https://your-app.com/webhook",
        "description": "Production endpoint",
        "events": ["job.completed", "job.failed"],
        "is_active": true,
        "created_at": "2026-01-15T10:00:00Z",
        "updated_at": "2026-01-15T10:00:00Z",
        "last_triggered_at": "2026-02-03T14:35:42Z",
        "failure_count": 0
      }
    ],
    "count": 1
  }
}

Create Webhook

POST/v1/webhooks

Request Body

Parameter	Type	Required	Description
`url`	string	Yes	HTTPS URL to receive webhooks
`events`	string[]	Yes	Events to subscribe to. Only events with `available: true` in the catalog can be subscribed — the API rejects the rest
`description`	string	No	Free-form label for the webhook

curl -X POST https://api.kawaa.com/v1/webhooks \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhook",
    "events": ["job.completed", "job.failed"]
  }'

The response includes the webhook's signing secret — store it to verify the X-Kawaa-Signature header on deliveries. Deliverable events: verification.completed, verification.failed, job.completed, job.failed, credits.low, credits.exhausted, blacklist.detected and dmarc.failure.verification.* events fire for single verifications (POST /v1/verify) — fresh verifications only, since cached results return synchronously; bulk jobs emit job.* events instead. credits.low is delivered at most once per 7 days and credits.exhausted at most once per 24 hours.

Update Webhook

PUT/v1/webhooks/{id}

Update the URL or subscribed events for an existing webhook.

Delete Webhook

DELETE/v1/webhooks/{id}

Remove a webhook subscription.

Test Webhook

POST/v1/webhooks/{id}/test

Send a test event to verify your webhook endpoint is working correctly.

Regenerate Secret

POST/v1/webhooks/{id}/secret

Generate a new signing secret for the webhook. The old secret will be immediately invalidated.

Available Events

GET/v1/webhooks/events

Get the webhook event catalog. Each event is an object with an available flag — only events with available: true can be subscribed to.

{
  "success": true,
  "data": {
    "events": [
      {
        "name": "job.completed",
        "description": "Triggered when a bulk verification job is completed",
        "category": "jobs",
        "available": true,
        "payload_example": {
          "event": "job.completed",
          "data": {
            "job_id": "job_abc123",
            "total_emails": 1000,
            "summary": { "valid": 800, "invalid": 150, "risky": 50 },
            "completed_at": "2025-01-01T00:00:00Z"
          }
        }
      },
      {
        "name": "verification.completed",
        "description": "Triggered when a single email verification completes",
        "category": "verification",
        "available": true,
        "payload_example": {
          "event": "verification.completed",
          "data": {
            "job_id": "job_abc123",
            "email": "user@example.com",
            "status": "valid",
            "quality_score": 95,
            "verified_at": "2025-01-01T00:00:00Z",
            "credits_used": 1
          }
        }
      }
    ]
  }
}