{"_id":"5719767ec863120e0012a056","project":"56008ba98c0c9d0d00dcaeb0","category":{"_id":"5719767ec863120e0012a045","version":"5719767ec863120e0012a042","project":"56008ba98c0c9d0d00dcaeb0","__v":0,"sync":{"url":"","isSync":false},"reference":true,"createdAt":"2016-01-25T21:10:29.130Z","from_sync":false,"order":1,"slug":"api","title":"API Documentation"},"user":"56008b651503430d007cc929","version":{"_id":"5719767ec863120e0012a042","hasDoc":true,"project":"56008ba98c0c9d0d00dcaeb0","__v":7,"hasReference":true,"createdAt":"2016-04-22T00:55:26.295Z","releaseDate":"2016-04-22T00:55:26.295Z","categories":["5719767ec863120e0012a043","5719767ec863120e0012a044","5719767ec863120e0012a045","5719767ec863120e0012a046","5719767ec863120e0012a047","5719767ec863120e0012a048","5719767ec863120e0012a049","57f45a18da14e71700d12e4a","582b71b15403840f008c0410","58c060cf3eee111b00a8b210","591e4c277f22100f00031521","591e4c3d094c5b0f006769fe","591e4c461e0dc20f0047b58b"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2.0"},"__v":1,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-19T01:26:05.159Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":true,"order":0,"body":"We've written up a guide on [creating a security workflow with Webhooks](doc:create-a-security-workflow-with-thisdatas-alert-webhooks). This document will give a bit more detail on what's in the webhook.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/Hau8JJXgSm234RV2aQ3q_thisdata_flow_diagram.png\",\n        \"thisdata_flow_diagram.png\",\n        \"1296\",\n        \"1176\",\n        \"#34abe4\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Webhook Format\"\n}\n[/block]\nThe webhook will be `POST`ed to the endpoint you configured in your API Settings.\n\nThe webhook payload is the original log-in event you sent to ThisData, with some additional attributes.\n\n  - **version** - versions the webhook format\n  - **was_user** - a boolean indicating the user's response:\n    - `null` - the user has not responded yet\n    - `false` - the user has confirmed it was **not** them\n    - `true` - the user has confirmed it was them\n  - **alert** - some information on the ThisData Alert\n    - **id**\n    - **description** - a brief description of the original alert\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"When will we send a webhook?\"\n}\n[/block]\nWe will send a webhook:\n  - when notice something unusual, and generate an alert\n  - _if we've sent a Was This You notification_ we'll send a webhook any time the user clicks an \"It was me\" or \"It wasn't me\" link\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Examples\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"version\\\" :  1,\\n  \\\"was_user\\\" : null,\\n  \\\"alert\\\" :    {\\n    \\\"id\\\" : 11223344,\\n    \\\"description\\\" : \\\"Eve Smith logged in from a new location\\\",\\n  },\\n  \\\"ip\\\" : \\\"1.2.3.4\\\",\\n  \\\"verb\\\" : \\\"log-in\\\",\\n  \\\"user_agent\\\" : \\\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3)...\\\",\\n  \\\"user\\\" : {\\n    \\\"id\\\" : \\\"112233\\\",\\n    \\\"name\\\" : \\\"Eve Smith\\\",\\n    \\\"email\\\" : \\\"eve.smith:::at:::domain.com\\\"\\n   },\\n   \\\"location\\\": {\\n    \\\"country_name\\\": \\\"United States\\\",\\n    \\\"country_iso_code\\\": \\\"US\\\",\\n    \\\"region_name\\\": \\\"New York\\\",\\n    \\\"city_name\\\": \\\"Brooklyn\\\",\\n    \\\"postal_code\\\": \\\"11237\\\",\\n    \\\"timezone\\\": \\\"America/New_York\\\",\\n    \\\"longitude\\\": -73.9235,\\n    \\\"latitude\\\": 40.7035\\n   }   \\n}\",\n      \"language\": \"json\",\n      \"name\": \"Alert Created\"\n    },\n    {\n      \"code\": \"{\\n  \\\"version\\\" :  1,\\n  \\\"was_user\\\" : false,\\n  \\\"alert\\\" :    {\\n    \\\"id\\\" : 11223344,\\n    \\\"description\\\" : \\\"Eve Smith logged in from a new location\\\",\\n  },\\n  \\\"ip\\\" : \\\"1.2.3.4\\\",\\n  \\\"verb\\\" : \\\"log-in\\\",\\n  \\\"user_agent\\\" : \\\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3)...\\\",\\n  \\\"user\\\" : {\\n    \\\"id\\\" : \\\"112233\\\",\\n    \\\"name\\\" : \\\"Eve Smith\\\",\\n    \\\"email\\\" : \\\"eve.smith@domain.com\\\"\\n   } \\n}\",\n      \"language\": \"json\",\n      \"name\": \"\\\"Was Not Me\\\" webhook payload\"\n    },\n    {\n      \"code\": \"{\\n  \\\"version\\\" :  1,\\n  \\\"was_user\\\" : true,\\n  \\\"alert\\\" :    {\\n    \\\"id\\\" : 11223344,\\n    \\\"description\\\" : \\\"Eve Smith logged in from a new location\\\",\\n  },\\n  \\\"ip\\\" : \\\"1.2.3.4\\\",\\n  \\\"verb\\\" : \\\"log-in\\\",\\n  \\\"user_agent\\\" : \\\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3)...\\\",\\n  \\\"user\\\" : {\\n    \\\"id\\\" : \\\"112233\\\",\\n    \\\"name\\\" : \\\"Eve Smith\\\",\\n    \\\"email\\\" : \\\"eve.smith@domain.com\\\"\\n   } \\n}\",\n      \"language\": \"json\",\n      \"name\": \"\\\"It was me\\\" payload\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Verifying the webhook's authenticity\"\n}\n[/block]\nTo authenticate the requests being sent to your webhook endpoint, you can use the Secret for Webhook Signatures, found in your API settings. [Learn more about the API Settings Page](doc:api-settings-page).\n\nWe will sign our webhooks using the shared secret and the body of the request, and add that as the ​X-Signature​ header. We calculate a SHA512 digest using the shared secret and the JSON-stringified body of the request.\n\nAn example of how one might authenticate the requests would be:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Calculate an HMAC for the webhook ThisData has sent us\\nkey = \\\"'Secret for Webhook Signatures' key copied from your settings page\\\"\\nbody = request.body\\ndigest = OpenSSL::Digest.new('sha512')\\nhmac = OpenSSL::HMAC.hexdigest(digest, key, body)\\n\\n# Verify it matches the signature they sent\\nif hmac == request.headers[\\\"X-Signature\\\"]\\n  # carry on\\nelse\\n  # someone is pretending to be ThisData\\nend\\n\\n\",\n      \"language\": \"ruby\",\n      \"name\": null\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"webhooks","type":"basic","title":"Webhooks"}
We've written up a guide on [creating a security workflow with Webhooks](doc:create-a-security-workflow-with-thisdatas-alert-webhooks). This document will give a bit more detail on what's in the webhook. [block:image] { "images": [ { "image": [ "https://files.readme.io/Hau8JJXgSm234RV2aQ3q_thisdata_flow_diagram.png", "thisdata_flow_diagram.png", "1296", "1176", "#34abe4", "" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "Webhook Format" } [/block] The webhook will be `POST`ed to the endpoint you configured in your API Settings. The webhook payload is the original log-in event you sent to ThisData, with some additional attributes. - **version** - versions the webhook format - **was_user** - a boolean indicating the user's response: - `null` - the user has not responded yet - `false` - the user has confirmed it was **not** them - `true` - the user has confirmed it was them - **alert** - some information on the ThisData Alert - **id** - **description** - a brief description of the original alert [block:api-header] { "type": "basic", "title": "When will we send a webhook?" } [/block] We will send a webhook: - when notice something unusual, and generate an alert - _if we've sent a Was This You notification_ we'll send a webhook any time the user clicks an "It was me" or "It wasn't me" link [block:api-header] { "type": "basic", "title": "Examples" } [/block] [block:code] { "codes": [ { "code": "{\n \"version\" : 1,\n \"was_user\" : null,\n \"alert\" : {\n \"id\" : 11223344,\n \"description\" : \"Eve Smith logged in from a new location\",\n },\n \"ip\" : \"1.2.3.4\",\n \"verb\" : \"log-in\",\n \"user_agent\" : \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3)...\",\n \"user\" : {\n \"id\" : \"112233\",\n \"name\" : \"Eve Smith\",\n \"email\" : \"eve.smith@domain.com\"\n },\n \"location\": {\n \"country_name\": \"United States\",\n \"country_iso_code\": \"US\",\n \"region_name\": \"New York\",\n \"city_name\": \"Brooklyn\",\n \"postal_code\": \"11237\",\n \"timezone\": \"America/New_York\",\n \"longitude\": -73.9235,\n \"latitude\": 40.7035\n } \n}", "language": "json", "name": "Alert Created" }, { "code": "{\n \"version\" : 1,\n \"was_user\" : false,\n \"alert\" : {\n \"id\" : 11223344,\n \"description\" : \"Eve Smith logged in from a new location\",\n },\n \"ip\" : \"1.2.3.4\",\n \"verb\" : \"log-in\",\n \"user_agent\" : \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3)...\",\n \"user\" : {\n \"id\" : \"112233\",\n \"name\" : \"Eve Smith\",\n \"email\" : \"eve.smith@domain.com\"\n } \n}", "language": "json", "name": "\"Was Not Me\" webhook payload" }, { "code": "{\n \"version\" : 1,\n \"was_user\" : true,\n \"alert\" : {\n \"id\" : 11223344,\n \"description\" : \"Eve Smith logged in from a new location\",\n },\n \"ip\" : \"1.2.3.4\",\n \"verb\" : \"log-in\",\n \"user_agent\" : \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3)...\",\n \"user\" : {\n \"id\" : \"112233\",\n \"name\" : \"Eve Smith\",\n \"email\" : \"eve.smith@domain.com\"\n } \n}", "language": "json", "name": "\"It was me\" payload" } ] } [/block] [block:api-header] { "type": "basic", "title": "Verifying the webhook's authenticity" } [/block] To authenticate the requests being sent to your webhook endpoint, you can use the Secret for Webhook Signatures, found in your API settings. [Learn more about the API Settings Page](doc:api-settings-page). We will sign our webhooks using the shared secret and the body of the request, and add that as the ​X-Signature​ header. We calculate a SHA512 digest using the shared secret and the JSON-stringified body of the request. An example of how one might authenticate the requests would be: [block:code] { "codes": [ { "code": "# Calculate an HMAC for the webhook ThisData has sent us\nkey = \"'Secret for Webhook Signatures' key copied from your settings page\"\nbody = request.body\ndigest = OpenSSL::Digest.new('sha512')\nhmac = OpenSSL::HMAC.hexdigest(digest, key, body)\n\n# Verify it matches the signature they sent\nif hmac == request.headers[\"X-Signature\"]\n # carry on\nelse\n # someone is pretending to be ThisData\nend\n\n", "language": "ruby", "name": null } ] } [/block]