Webhook Endpoints

Webhooks in Similarweb: Real-Time Notifications for Your Data Needs
Webhooks offer a powerful way to stay informed about events and updates from the Similarweb API in real-time. By subscribing to webhook notifications, you can ensure that your applications and systems are always up-to-date with the latest insights without the need for constant polling. In this guide, we'll walk you through the process of setting up and managing webhooks in your Similarweb API integration.

Introduction to Webhooks
Webhooks are a mechanism for receiving real-time notifications when specific events occur within the Similarweb API. Instead of repeatedly querying the API for updates, webhooks allow Similarweb to send POST requests directly to your specified endpoints as soon as an event of interest takes place.

Real-time updates - Know immediately when your report is available to download.
Automations - Create automations around your reporting and dashboards.

Setting Up Webhooks

1. Configure Your Endpoint: Create a URL in your application that can receive HTTP POST requests from Similarweb.
2. Integrate Webhook into Reports: In your Similarweb API account settings, find the section for webhooks and add the URL you've created.

Step-by-step guide -

1. Use the Check Webhook Endpoint to validate that your webhook integration was successful:

POST https://api.similarweb.com/v3/batch/webhooks/test

{
	"webhook_url": "http://slack.com/example_url/abc"
}

import requests

url = "https://api.similarweb.com/v3/batch/webhooks/test"

payload = "{\n\"webhook_url\": \"http://slack.com/example_url/abc\"\n}"
headers = {
  'api-key': '{{api_key}}'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

The notification will perform a POST method with the following body:

{
    "event_type": "test_webhook_endpoint",
    "payload": 'Webhook Integration with Similarweb is successful!'
}

Check within your internal system that you have indeed got the "test_webhook_endpoint" event from us, the event should be invoked immediately.

🚧

Timeout will be after 5 seconds, timeout will cause failure.

2. Once you have validated that your URL is compatible with our webhook system you can now use it with our Report Endpoints.

POST https://api.similarweb.com/v3/batch/traffic_and_engagement/request-report
 
{
    "webhook_url": "http://slack.com/example_url/abc",
    "domains":[
        "amazon.com"
    ],
    "category_ids": [2335752011],
    "metrics":[
        "category_sales_performance_product_views",
        "category_sales_performance_units_sold",
        "category_sales_performance_revenue",
        "category_sales_performance_cvr"
    ],
    "start_date": "2021-09",
    "end_date": "2021-11",
    "granularity": "monthly",
    "response_format": "csv"
}

When the report status changes it will trigger the webhook.

📘

Possible Report Statuses:

"processing", "complete", or "internal_error".