How can I 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 Webhooks 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 last event date your subscription got 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 (see above).

{   
"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: NotAcceptable → 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.

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.

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.

Was this article helpful?
1 out of 1 found this helpful