How Do I Use Webhooks in Echosec?

Webhooks enable you to receive Echosec notifications in non-email applications.

Using Webhooks

Echosec can send webhook events to an endpoint of your choosing when a Saved Search notification is triggered. The webhook message body contains information on the search that generated the notification, as well as data Echosec received from the social media or news post.

Webhooks are only necessary if you need to take programmatic action on key content discovered by Echosec. If not, it is best to use email notifications, which can be sent to multiple addresses and include batch and digest options that are unavailable through webhooks.

Configuring Webhooks

You must have an Echosec enterprise license to configure webhooks. To set up webhooks:

  1. Save a search in Echosec or navigate to an existing Saved Search.
  2. Navigate to the Saved Search's notification settings.
  3. Select the webhook icon under "Email/Webhook Destinations."
  4. Enter the URL endpoint(s) you wish to receive events from.

Receiving Webhooks

CSRF Protection


It is very important that any of your webservers or webhook endpoints have disabled CSRF protection on the route saved as a Saved Search webhook destination.

Content Headers

Echosec will send all webhooks events with the application/json content-type header.

Events


Echosec sends a single webhook event for each post that generates Saved Search notifications.

JSON Event
  • JSON Body

The JSON structure of the webhook for version 1 of the API is as follows:

{
"version": 1,
"data": {
"savedSearch": { ... },
"notification": { ... }
}
}
  • SavedSearch Schema

The embedded Saved Search schema for version 1 of the API is as follows:

{
"id": 1,
"createdAt": 1525378673,
"favorite": false,
"startAt": 1515110400,
"endAt": 1525377700,
"address": "Toronto, ON, Canada",
"addressBounds": "POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))",
"authorQuery": "",
"authorId": "",
"imagesOnly": false,
"videoOnly": false
}
  • Notification Schema

The content which the Saved Search deemed as “notification” worthy:

{
"createdAt": 1525378673,
"content": {
"id": "992075562653892608",
"tags": [
"hello",
"world"
],
"type": "social_media_post",
"places": "",
"authorId": "123456789",
"location": "",
"postLink": "https://example.org",
"provider": "twitter",
"authorUrl": "https://example.org/author/123456789",
"createdAt": 1525364220,
"echosecId": "cc7a59e9-9f98-5898-9eb6-09349183e9ce",
"placeName": "Los Angeles, CA",
"titleText": "",
"authorName": "bob",
"photoLarge": "",
"videoLarge": "",
"contentText": "social media content",
"generatedBy": "twitter",
"photoNormal": "",
"videoNormal": "",
"authorThumbnail": "https://example.org/author/123456789/author.jpg",
"authorScreenName": "Bob",
"contentFormatted": ""
}
}

 

Please contact us if you need help setting up webhooks.