Skip to main content
Kernel can send HTTP callbacks (webhooks) when jobs complete or fail. This lets you receive results without polling.

​
Enabling webhooks

Include a webhook_url field when creating a job. Both entity resolution and firmographic enrichment support webhooks: Entity resolution:
curl
curl -X POST https://api.kernel.ai/rest/v1/entity-resolution \
  -H "x-api-key: $KERNEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"legal_name": "Stripe", "webhook_url": "https://example.com/webhooks/kernel"}'
Firmographic enrichment (via the service API):
curl
curl -X POST https://api.kernel.ai/rest/v1/firmographics \
  -H "x-api-key: $KERNEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kernel_id": "6347422643", "webhook_url": "https://example.com/webhooks/kernel"}'
The URL must be an HTTPS URL that accepts POST requests.

​
Webhook payload

When a job completes or fails, Kernel sends a POST request to your webhook_url with the following JSON body: 
{
  "event": "entity-resolution.completed",
  "timestamp": "2026-06-08T15:30:00Z",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "created_at": "2026-06-08T15:00:00Z",
    "completed_at": "2026-06-08T15:00:32Z",
    "record": { ... }
  }
}
For failed jobs, status is "failed" and record is null: 
{
  "event": "entity-resolution.failed",
  "timestamp": "2026-06-08T15:31:00Z",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "failed",
    "created_at": "2026-06-08T15:00:00Z",
    "completed_at": "2026-06-08T15:00:32Z",
    "record": null
  }
}

​
Event types

EventTrigger
entity-resolution.completedAn entity resolution job finished successfully
entity-resolution.failedAn entity resolution job failed
firmographic-enrichment.completedA firmographic enrichment job finished successfully
firmographic-enrichment.failedA firmographic enrichment job failed

​
Request headers

HeaderDescription
Content-Typeapplication/json
X-Kernel-Signaturesha256=<HMAC-SHA256 hex digest> — verify this to confirm the payload is from Kernel
X-Kernel-EventThe event type (e.g. entity-resolution.completed)
X-Kernel-DeliveryA unique ID for this delivery attempt

​
Verifying signatures

Your signing secret is generated when you create an API key and is shown once. To verify a webhook:
  1. Compute the HMAC-SHA256 of the raw request body using your signing secret
  2. Compare the result (as hex) to the value in the X-Kernel-Signature header (after removing the sha256= prefix)
  3. Use a constant-time comparison to prevent timing attacks
import hmac, hashlib

def verify_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature.removeprefix("sha256="))

​
Retry policy

If your endpoint returns a non-2xx status or times out (5 second limit), Kernel retries up to 3 times with exponential backoff:
AttemptDelay
1Immediate
230 seconds
32 minutes
After 3 failed attempts, the delivery is marked as permanently failed.