Guides
Go to SimilarwebContact us
Start typing to search…

API Endpoints

1. Description

Endpoint: http://api.similarweb.com/v4/sales-signals/describe
Method: GET
No request body required.

Purpose:

Before you do anything, use the description endpoint to see what values are supported for each signal type.

⚠️

Why? The API is strict—only supported values are accepted. Enter something unsupported and you'll get a clear error.

What You Get from Description:

  • Allowed percentages, metrics, periods, thresholds and directions for traffic and new market signals
  • List of topics and countries for intent signals
  • List of technologies for technology signals
  • List of ad networks and directions for ad network signals
  • List of news categories for news signals

Practical tip:

Always check the description endpoint before configuring or changing signals. Don't guess.

2. Signals: Creating and Managing What You Track

There are different endpoints and required parameters for each signal type.

Supported types:

  • Traffic Change
  • New Market
  • Intent
  • AdNetwork
  • Technology changes
  • News

Process:

  1. Step 1: Decide what type of signal you need
  2. Step 2: Check the description endpoint for required/allowed values
  3. Step 3: Use the relevant signal creation endpoint and fill in the model with all required parameters

Error Handling:
If you submit a value that's not supported (wrong percentage, metric, action, etc.), you'll get a specific error. You cannot set up something the API doesn't allow.

Signals - Get All

Endpoint: /v4/sales-signals/signals/all
Method: GET
No request body required.

Allows you to view your created signals, including filters, type, subtype, ID, and status. Status can be active or deactivated (pause signals you don't want results for). Use the archive endpoint to toggle status.

Signals - Create Traffic Change

Endpoint: http://api.similarweb.com/v4/sales-signals/signals/traffic
Method: POST

{
    "traffic_changes":{
        "metric": "string",
        "direction": "string",
        "period": "string",
        "country": "string",
        "value": "number"
    }
}

Signals - Create New Market

Endpoint: http://api.similarweb.com/v4/sales-signals/signals/traffic
Method: POST

{
  "new_markets": {
    "metric": "string",
    "countries": ["string"],
    "threshold_value": "number"
  }
}

Note: Both traffic_changes and new_markets can not be included in a single request

Signals - Create News

Endpoint: http://api.similarweb.com/v4/sales-signals/signals/news
Method: POST

{
  "categories": ["string"],
  "period": "string"
}

Signals - Create Intent

Endpoint: http://api.similarweb.com/v4/sales-signals/signals/intent
Method: POST

{
  "topics": ["string"],
  "countries": ["string"]
}

Signals - Create AdNetworks

Endpoint: http://api.similarweb.com/v4/sales-signals/signals/ad-network
Method: POST

{
  "ad_network_ids": ["string"],
  "action": "string"
}

Signals - Create Technology

Endpoint: http://api.similarweb.com/v4/sales-signals/signals/technology
Method: POST

{
  "period": "string",
  "type": "string",
  "technology_categories": ["string"],
  "technology_sub_categories": ["string"],
  "technologies": ["string"]
}

Signals - Deactivate

Endpoint: http://api.similarweb.com/v4/sales-signals/signals/archive
Method: POST

{
  "id": "string"
}

3. Webhooks: Where the Signals Go

An endpoint (URL) where the API sends notifications about signals you've set up.

Creating Webhooks:

  • Callback URL: Where notifications should be sent
  • Signals per hook: How many signal events are sent in each HTTP request
  • Signal types: Which types of signals should use this URL

Examples:

  • Only receive technology signals at a specific URL
  • Use one URL for all five types of signals (traffic, new market, intent, etc.)

Once created, the webhook starts receiving events immediately.

Webhooks - Add

Endpoint: http://api.similarweb.com/v4/sales-signals/webhook-subscriptions/add
Method: POST

{
  "callback_url": "string",
  "signals_per_hook": "integer",
  "signal_types": ["string"]
}

Webhooks - Get All Subscriptions

Endpoint: http://api.similarweb.com/v4/sales-signals/webhook-subscriptions/all
Method: GET
No request body required.

See all your webhooks, their status (active/deactivated), which signal types they cover, how many signals per hook, and a creation timestamp.

Webhooks - Unsubscribe

Endpoint: http://api.similarweb.com/v4/sales-signals/webhook-subscriptions/archive
Method: POST

{
  "id": "string"
}

Deactivate a webhook by its ID (stops sending events).

Webhooks - Verify Signature

Endpoint: http://api.similarweb.com/v4/sales-signals/webhook-subscriptions/authorize
Method: POST

Verify the authenticity of a webhook delivery. Compares the HMAC-SHA256 signature in the x-sw-authorization header against a computed signature of the raw request body.

Headers:
x-sw-authorization: Base64-encoded HMAC-SHA256 signature from the webhook delivery

Request Body: Raw body content from the webhook delivery (read as-is, not parsed).

Response:
200 OK — Signature is valid
406 Not Acceptable — Signature verification failed

4. Domains: Specify What Websites/Companies to Track

You must subscribe domains to receive signals about them.

Pro tip:

Automate subscriptions using your CRM. For example, subscribe a domain when a new lead/account/contact is created in Salesforce or HubSpot. Unsubscribe when an account is no longer relevant (e.g., changes status in CRM).

Domains - List

Endpoint: http://api.similarweb.com/v4/sales-signals/domains/list
Method: POST

{
  "page": 1,
  "page_size": 1000
}

List domains you are currently subscribed to for signal monitoring. Results are paginated.

Domains - Subscribe

Endpoint: http://api.similarweb.com/v4/sales-signals/domains/subscribe
Method: POST

{
  "domains": ["string"]
}

Domains - Unsubscribe

Endpoint: http://api.similarweb.com/v4/sales-signals/domains/unsubscribe
Method: POST

{
  "domains": ["string"]
}

5. Events: Monitoring, Troubleshooting, and Replay

Every signal notification sent by the API is an event. The events endpoints let you search, monitor, and retry signal deliveries.

5.1 Viewing Event History

  • Search by event ID, status (notified, failed), date range, or subscription ID (webhook)
  • Results are paginated due to potentially high volume
  • For now, you can access two months of history

5.2 Troubleshooting Failed Events

  • Filter by status to see failed deliveries
  • Useful if your server had downtime or temporary issues

5.3 Re-sending Events

  • Use the resend endpoint for all failed events in the past two months
  • Filter by period or specific event IDs for more targeted resends

Events - History

Endpoint: http://api.similarweb.com/v4/sales-signals/events/history
Method: POST

{
  "subscription_id": "string",
  "date_from": "integer",
  "date_to": "integer",
  "status": "string",
  "ids": ["string"],
  "page": "integer",
  "page_size": "integer"
}

Events - Resend

Endpoint: http://api.similarweb.com/v4/sales-signals/events/resend
Method: POST

{
  "subscription_id": "string",
  "date_from": "integer",
  "date_to": "integer",
  "status": "string",
  "ids": ["string"]
}

Updated about 14 hours ago