Webhooks

Create a webhook subscription

Subscribes a public HTTPS URL to a project event. LLM Pulse POSTs a JSON envelope (event, occurred_at, project_id, subscription_id, data) to the URL every time the event occurs, signed via the X-LLMPulse-Signature header (HMAC-SHA256 of the raw body computed with the subscription secret). Failed deliveries receive up to 5 attempts in total, including the first, with backoff; subscriptions auto-disable after 20 consecutive failed deliveries. While the account is below the Scale plan its subscriptions are kept but deliver nothing: no failed delivery is counted, none is disabled, and deliveries resume once the account is back on Scale or above, without resending the events from that period. Each delivery also checks that the API key that created the subscription still covers its project: an API key limited to some projects that loses the project stops the subscription for good. Idempotent for the same project + event + URL: re-posting returns the existing subscription, unless the API key or OAuth connection that created it was revoked, or that API key no longer covers the project; then it is replaced by a new subscription with a new secret. The response carries secret when it creates the subscription, and on a re-post only for the API key or OAuth connection that created it: any other credential gets the subscription without secret. Requires a read_write scope API key and the Scale plan or above.

post/webhooks

Request

  • Base URL
    https://api.llmpulse.ai/api/v1
  • URL
    https://api.llmpulse.ai/api/v1/webhooks
  • Auth
    API key in header Authorization

Request body

project_idinteger required
event_type'mention.created' | 'competitor_mention.created' | 'citation.created' | 'prompt_execution.completed' | 'sentiment.negative_detected' | 'recommendation.completed' | 'intelligence_task.completed' | 'intelligence_task.updated' | 'geo_audit_run.completed' | 'geo_audit_alert.triggered' required
target_urlstring required

Public HTTPS URL that will receive signed event payloads

Response

Created, or the existing subscription on a re-post. The signing secret is only returned by this endpoint, and on a re-post only to the credential that created the subscription.

idinteger
project_idinteger
event_type'mention.created' | 'competitor_mention.created' | 'citation.created' | 'prompt_execution.completed' | 'sentiment.negative_detected' | 'recommendation.completed' | 'intelligence_task.completed' | 'intelligence_task.updated' | 'geo_audit_run.completed' | 'geo_audit_alert.triggered'
target_urlstring
disabledboolean

True when the subscription receives no more events, including when the API key or OAuth connection that created it was revoked, or when that API key is limited to some projects and no longer covers the subscription's project. Creating it again with the same project, event and URL replaces it with a new subscription and secret.

failure_countinteger
last_delivered_atstring date-time nullable
created_atstring date-time
secretstring

HMAC signing secret (whsec_...). Returned when the subscription is created, and on a re-post only to the API key or OAuth connection that created it; absent for any other credential.

request_idstring

Changes

No recorded changes to this operation across all 32 revisions of this API.