Data Notifications / webhooks

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.

Why subscribe to data release notifications via Webhooks?

With Similarweb’s Webhooks, you can subscribe to event notifications via the API to be instantly updated when new daily and monthly website data is released.

Rather than making an API call to check the latest date of available data, simply subscribe to Webhooks by specifying a URL, and Similarweb will trigger a notification to it once new data becomes available.

Webhook Events

You can subscribe to two types of events:

Daily: a specific date's data is released within 72 hours after the end of that date (EST time zone). For example, data for the 14th will typically be published by the end of the day on the 17th (EST).

Monthly: monthly data is released by the 10th of the following month. In most cases, it is released sooner.

The URL in the subscription should be a POST endpoint, and it will be triggered with the following body:

{   
  "subscription_id": "1hb87575e7-b56e-45e4-9d3534569bcb9c90",   
  "latest_data_available": "2021-10-19",   
  "webhook_event_type": "Daily",   
  "created": "1634629790",
  "text": "Hi! New daily data is available. The latest day is 2021-10-19"
}

Webhook Object Attributes

subscription_id [String] - The unique ID per account and subscription

latest_data_available [String YYYY-MM-DD] - Reflects the most recent date of available data.

webhook_event_type [String] - Can be either “Daily” or “Monthly”

created [String] - Time at which the object was created. Measured in seconds since the Unix epoch.

text [String] - a descriptive element, which includes the most recent date of available data.

The message will contain the following header field that will be used as a signature for a later authentication (see ‘Authentication’ below):

x-sw-authorization YIFFW56koaZ/xCGg1j7357F/JjYQ66Bd/rGu78hjpyo=

This authorization token is used to authenticate that your endpoint was triggered by a trusted source (i.e., Similarweb). The token expires after 5 minutes.

Subscribe to a Webhook

POST

https://api.similarweb.com/v1/webhooks/subscribe?api_key={similarweb_api_key}

*Body (required)

{   
"webhook_event_type": "Daily",   
"url": "https://foo.com"
}

Response:

{
   "subscription_id": "1456e7-b50e-4554-9d35-8845656560",
   "webhook_event_type": "Daily",
   "url": "https://foo.com",
   "last_update_date": null
}

View your existing Webhook subscriptions

GET

https://api.similarweb.com/v1/webhooks/subscriptions?api_key={similarweb_api_key}

Response:

{
       "subscription_id": "brdfh9fe-0cg8-42fg-afge-56dfhg258d0",
       "webhook_event_type": "Monthly",
       "url": "https://foo.com",
       "last_update_date": "2021-10-15"
}

"last_update_date": is the most recent date your subscription received an update.

Unsubscribe from a webhook

PUT

https://api.similarweb.com/v1/webhooks/unsubscribe/{subscription_id}?api_key={similarweb_api_key}

Authentication

This allows you to authenticate that your endpoint was triggered by a trusted source (i.e. Similarweb).

POST

https://api.similarweb.com/v1/webhooks/authorize?api_key={similarweb_api_key}

Body should contain the same body that was sent when your webhook was triggered .

{   
"subscription_id":  "1hb87575e7-b56e-45e4-9d3534569bcb9c90",   
"latest_data_available": "2021-10-19",   
"webhook_event_type": "Daily",   
"created": "1634629790"
"text": "Hi! New daily data is available. The latest day is 2021-10-19"
}

Header field

X-sw-authorization YIFFW56koaZ/xCGg1j7357F/JjYQ66Bd/rGu78hjpyo=

Response Index

200: Ok → Authentication succeeded, your webhook was triggered by Similarweb.

406: Not Acceptable → Authentication failed, your webhook was not triggered by Similarweb.

424: Failed Dependency → Authentication failed. Your webhook was triggered by Similarweb but the authorization token expired. This means that more than 5 min has passed since the trigger.

FAQs

Q: Does this include App data?

No. Currently, these webhooks are for website data only.

Q: Will I be charged API hits for subscribing?

No, the Webhooks service does not cost any API hits.

Q: Is there a timeout limit?

A: Yes, there is a 100-second timeout per webhook subscription. During this time period, the webhook subscription expects to receive a response back or it will fail to update the subscription with the current daily/monthly snapshot.

👍
Need help?
If you have any questions or would like to speak to one of our dedicated technical API specialists, please reach out to your Account Manager.