Webhooks

Where do I set up webhooks?

Open Settings, then Integrations in the Spiderlook app. Add an HTTPS endpoint URL, choose the events you want, and save. Spiderlook shows the signing secret once when you create the endpoint. Store it with your receiver.

Use Send test to confirm your receiver accepts deliveries before you rely on live events.

Which events can I subscribe to?

Events are grouped the same way as the Integrations picker. Entity types in payloads are rival, benchmark, and your_brand.

• member.added. A teammate joined your Organization.
• member.removed. A teammate left your Organization.
• organization.updated. Organization settings changed.
• project.created. A Project was created.
• project.updated. A Project was updated.
• project.deleted. A Project was deleted.
• entity.added. A rival, benchmark, or Your brand was added.
• entity.removed. A rival, benchmark, or Your brand was removed.
• entity.moved_between_projects. An entity moved between Projects.
• tracking.toggled. Daily scans were turned on or off for an entity.
• entity.ready. First analysis finished and the entity is ready.
• battlecard.created. A battlecard was created.
• battlecard.updated. A battlecard was updated.
• new_meta_ad_detected. New Meta ads appeared for a tracked entity.
• new_google_ad_detected. New Google ads appeared for a tracked entity.
• website_change_detected. Website page changes were detected.
• new_social_post_detected. New social posts were detected.
• scan_completed. A scan run finished for an entity.

Send test delivers webhook.test so you can verify the receiver without waiting for a live event.

What does a delivery payload look like?

Every delivery is a JSON body with project context, the entity (when relevant), an item object for event-specific fields, and a deep_link into the Spiderlook app.

{
  "project_id": "019abc...",
  "entity_id": "019def...",
  "entity_type": "rival",
  "project": {
    "id": "019abc...",
    "slug": "acme",
    "name": "Acme",
    "organization_id": "019org...",
    "organization_slug": "nebula"
  },
  "entity": {
    "id": "019def...",
    "type": "rival",
    "kind": "competitor",
    "name": "Rival Co",
    "url": "https://rival.example"
  },
  "item": {
    "channel": "meta_ads",
    "inserted": 1,
    "updated": 0
  },
  "deep_link": "https://app.spiderlook.com/nebula/acme/rivals/019def..."
}

Which headers arrive with each delivery?

Spiderlook POSTs JSON to your URL with these headers so you can route and verify each delivery.

• Content-Type: application/json
• X-Spiderlook-Event: event type (for example new_meta_ad_detected)
• X-Spiderlook-Delivery: unique delivery id
• X-Spiderlook-Timestamp: Unix timestamp used in the signature
• X-Spiderlook-Signature: t=<timestamp>,v1=<hex digest>

How do I verify the signature?

Compute HMAC-SHA256 over the string "<timestamp>." plus the raw request body bytes, using your endpoint signing secret. Compare the hex digest to the v1 value in X-Spiderlook-Signature. Reject the request when the digest does not match.

signed = f"{timestamp}.".encode() + raw_body
digest = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
# header format: t=<timestamp>,v1=<digest>

How do retries and auto-disable work?

Spiderlook expects a 2xx response within 10 seconds. Network failures, HTTP 429, and 5xx responses are retried with exponential backoff (up to 8 attempts, backoff capped at 10 minutes). Other 4xx responses fail permanently for that delivery.

After 10 recorded failures on an endpoint, Spiderlook disables the subscription so a broken receiver cannot keep failing quietly. Re-enable it in Settings, then Integrations after you fix the URL or receiver.

How do I send a test delivery?

In Settings, then Integrations, open the endpoint and choose Send test. Spiderlook delivers webhook.test with a short payload that includes your subscription id, so you can confirm signature checks and routing before live traffic arrives.

Related