Subscribe to an app's installs or removals

• Auth: API key (Authentication)
• Scope: events:read
• Cost: Free to create; 10 credits per change delivered, refunded if delivery fails.

Use it instead of pulling an app's list or GET /v1/events on a schedule and diffing. Keep the secret from the response: it is shown once and signs every delivery (see Webhooks).

From now on, each time a scan detects a store installing or removing app (filtered by types and the optional company filters), we POST it to url within about a minute of the scan, as a WebhookPayload whose data is the same row GET /v1/events returns. Scans are weekly per store, so a change reaches you within a week of happening rather than whenever you next pull and diff a list.

Price: free to create; 10 credits per change delivered (one store, one install or removal), taken before the first send and refunded if every retry fails. A change your balance cannot cover waits (awaiting_credits) and is sent once you top up, for up to 7 days. Needs an account that has bought a credit pack (paid_plan_required otherwise). At most 25 active webhooks per account.

Delivery: url must be https on port 443 at a public address. Any 2xx is success; anything else, a timeout (10s) or a redirect is retried after 1, 5 and 30 minutes, 2, 6, 12 and 24 hours. After 3 deliveries in a row fail every retry, the webhook is disabled. Deliveries may arrive out of order and, rarely, more than once: deduplicate on the Installgraph-Webhook-Id header (the payload's id).

Verifying: Installgraph-Signature: t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 of <t>.<raw body> keyed by the secret returned here (shown once). Compare in constant time and refuse a t more than 5 minutes old. Scope events:read.

Request

curl -X POST "https://api.installgraph.com/v1/webhooks" \
  -H "Authorization: Bearer $INSTALLGRAPH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"app":"klaviyo","url":"https://example.com/hooks/installgraph","types":["removed"],"country":"US"}'

Body

JSON.

Response

200. The example's stores are fictional.

{
  "data": {
    "id": "6731b2e4c9a1f20d8e4b7c15",
    "app": {
      "slug": "klaviyo",
      "name": "Klaviyo",
      "category": "email-sms"
    },
    "types": [
      "removed"
    ],
    "filters": {
      "country": "US"
    },
    "url": "https://example.com/hooks/installgraph",
    "description": null,
    "status": "active",
    "disabledReason": null,
    "creditsPerDelivery": 10,
    "createdAt": "2026-11-10T12:00:00.000Z",
    "lastDeliveredAt": null,
    "secret": "whsec_3q2-7wEXAMPLEc9Lr0m4NnT1vYbZk8sFhGdJpQ6uXaW0"
  },
  "meta": {
    "requestId": "6f1c2a9e-4b7d-4e2a-9c51-0d3b8e7f2a14",
    "creditsUsed": 0,
    "creditsCharged": 0,
    "creditsRemaining": 2490,
    "freeRepulls": 0
  }
}

Fields

Every keyed response also carries meta (requestId, creditsUsed, creditsRemaining, freeRepulls) and the X-Credits-* and X-RateLimit-* headers. See Credits and Rate limits.

Errors

All codes: Errors.