Connect external tools to PromptLab via Webhooks and API

Learn how to authenticate with the PromptLab API, set up webhooks to receive real-time deal events, and verify incoming payloads securely.

PromptLab's API and webhook system lets you integrate your pipeline data with external tools, automate workflows, and build custom applications on top of your deal, contact, and activity data. You can pull data on demand via the REST API or receive real-time notifications via webhooks whenever key events occur in your pipeline.

Webhooks and API access are available on the Business plan and above.

Getting your API key

PromptLab uses API keys for authentication. Each key is scoped to your account and carries full access to the API endpoints available on your plan.

Open API key settings

Go to Settings > API Keys.

Generate a new key

Click Generate Key, give it a descriptive label (for example, the name of the integration or service that will use it), and click Create.

Copy the key

Copy the key immediately — PromptLab only shows it once. Store it in a secure secrets manager.

Add the key to your requests

Pass the API key as a Bearer token in the Authorization header of every API request:

Authorization: Bearer YOUR_API_KEY

Keep your API key secret. If a key is exposed, rotate it immediately from Settings > API Keys by revoking the compromised key and generating a new one.

Setting up webhooks

Webhooks let PromptLab push real-time event data to a URL you control — no polling required.

Open webhook settings

Go to Settings > Integrations > Webhooks.

Add a new endpoint

Click Add Endpoint.

Enter your endpoint URL

Paste the HTTPS URL where PromptLab should send event payloads. Your endpoint must be publicly reachable and return a 2xx status to acknowledge receipt.

Select events to subscribe to

Choose one or more events from the list. PromptLab will only send payloads for the events you select. See Webhook events below for the full list.

Save and confirm

Click Save. PromptLab immediately sends a test ping to your endpoint. Check your server logs to confirm the ping was received.

Webhook events

Event	Description
`deal.created`	A new deal is added to your pipeline
`deal.stage_changed`	A deal moves to a new pipeline stage
`meeting.recorded`	A call or meeting recording becomes available
`quote.sent`	A quote is sent to a customer
`task.created`	A new task is created on a deal or contact

Verifying webhook payloads

Every webhook request that PromptLab sends includes a signature header so you can confirm the payload came from PromptLab and has not been tampered with.

To verify a payload:

Retrieve the signature from the X-PromptLab-Signature header on the incoming request.
Compute an HMAC-SHA256 hash of the raw request body using your webhook secret (shown when you create or edit an endpoint under Settings > Integrations > Webhooks).
Compare your computed hash to the value in the signature header. If they match, the payload is authentic.

Reject any request where the signature does not match.

Example webhook payload

The following is a sample payload for the deal.stage_changed event:

{
  "event": "deal.stage_changed",
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "deal_id": "deal_abc123",
    "deal_name": "Acme Manufacturing - Q1 RFQ",
    "previous_stage": "Qualified",
    "new_stage": "Proposal Sent",
    "updated_by": "sales.rep@company.com"
  }
}

All webhook payloads use JSON. The top-level event field identifies the event type, timestamp is in ISO 8601 UTC format, and data contains the event-specific fields.

Rate limits

API rate limits apply based on your plan. If you exceed your limit, the API returns a 429 Too Many Requests response. Use the Retry-After header in the response to determine when you can resume requests.