Skip to main content

​
Overview

Puffle uses Svix for reliable webhook delivery. Webhooks let you receive events in real time instead of polling the API. Supported events:
  • signal.detected — A new signal has been detected and scored
  • research.complete — A deep research report has finished processing
  • research.failed — A deep research request could not be completed

​
Setup

1

Get the portal URL

Call the webhook portal endpoint to get a short-lived Svix management URL:
curl -s \
  -H "Authorization: Bearer pk_live_abc123" \
  "https://app.getlima.ai/api/v1/partners/portal"
Response:
{ "url": "https://app.svix.com/login?token=appPortal.eyJ..." }
2

Open the portal

Open the returned URL in a browser. It expires after 5 minutes.
3

Add your endpoint

In the Svix portal, click Add Endpoint, enter your HTTPS URL, and select the event types you want to receive.
4

Save your signing secret

Copy the endpoint’s signing secret from the Svix portal. You’ll use it to verify webhook signatures.

​
Payload Format

All webhook payloads share a common envelope: 
{
  "type": "signal.detected",
  "timestamp": "2026-04-20T10:30:00Z",
  "data": {
    "..." : "..."
  }
}

​
signal.detected

{
  "type": "signal.detected",
  "timestamp": "2026-04-20T10:30:00Z",
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "signal_type_label": "Hiring",
    "headline": "Acme Corp is hiring a VP of Engineering",
    "score": 87,
    "source": "linkedin_jobs",
    "detected_at": "2026-04-20T10:30:00Z"
  }
}

​
research.complete

{
  "type": "research.complete",
  "timestamp": "2026-04-20T10:33:22Z",
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440001",
    "first_name": "Jane",
    "last_name": "Smith",
    "company": "Acme Corp",
    "icp_score": 91,
    "report_url": "https://app.getlima.ai/api/v1/deep-research/770e8400-e29b-41d4-a716-446655440001"
  }
}

​
Signature Verification

Every webhook request includes a svix-signature header. Verify it using the Svix SDK to ensure the payload came from Puffle: 
from svix.webhooks import Webhook

def verify(payload: bytes, headers: dict, secret: str) -> dict:
    wh = Webhook(secret)
    return wh.verify(payload, headers)
Always verify webhook signatures before processing payloads. Unverified webhooks are a security risk.

​
Delivery & Retries

Svix retries failed deliveries with exponential backoff over 3 days. You can view delivery logs and manually retry from the Svix portal. Your endpoint must return a 2xx status within 30 seconds, or the delivery is considered failed and queued for retry.