{"__v":0,"_id":"5719767ec863120e0012a04b","category":{"version":"5719767ec863120e0012a042","project":"56008ba98c0c9d0d00dcaeb0","_id":"5719767ec863120e0012a046","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-03-29T02:42:36.350Z","from_sync":false,"order":5,"slug":"integrations-1","title":"Integrations"},"parentDoc":null,"project":"56008ba98c0c9d0d00dcaeb0","user":"564a46904fa1460d00780c0d","version":{"__v":4,"_id":"5719767ec863120e0012a042","hasDoc":true,"hasReference":true,"project":"56008ba98c0c9d0d00dcaeb0","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"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-29T02:43:40.138Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"Industry best practice is to notify your users when their account is accessed in an unusual way. Big guns like Google, Facebook, and Salesforce do it. And if you're already using [Segment](https://segment.com), it'll take 30 seconds for you to do it too!\n\nSegment allows you to set up Webhook endpoints so that, as well as having data sent to integrations like Intercom or Mixpanel, it'll also be sent to other websites via their APIs. We've got an endpoint which makes it super easy to integrate ThisData with Segment. Here's how to do it:\n\nIn ThisData:\n\n- [Log in to your ThisData account](https://thisdata.com/sign-in) (or [sign up for free](https://thisdata.com/sign-up))\n- Click API Settings\n- Copy your API key\n\nCombine your API key with our webhook endpoint URL like this:\n`https://api.thisdata.com/v1/segment/receive?api_key=YOUR_API_KEY_HERE`\n\nJust switch out `YOUR_API_KEY_HERE` for your real API key.\n\nOn Segment:\n\n- [Log in to Segment](https://segment.com/login)\n- Go to the \"Integrations\" tab for the Source you want to track\n- Find and click on the \"Webhooks\" integration\n- Click on \"Settings\"\n- In the \"Webhook URLs\" text box, paste the ThisData webhook URL (including your API key), which you made above\n- Click \"Save Changes\"\n- Click \"Enable Integration\"\n- Done!\n\n![The Segment webhook settings panel, with a ThisData webhook URL pasted in](https://thisdata.com/blog/content/images/2016/04/segment_webhook_setting.jpg)\n\nNow events you send to Segment will also flow through to your ThisData account. We'll begin monitoring for anomalous behaviour, and when it's spotted, take action. This could be by emailing the user, notifying you, sending a webhook to your app; it's all configurable on your ThisData API Settings page.\n\nCongratulations on taking the first steps towards automating your security with ThisData using Segment.\n\nNow we'll dive a little deeper in to some more areas to consider. These steps might take another ten minutes to nail.\n\n### Do I need to change my Segment calls?\n\nYou're off to a great start already, but it's even better if you're able to send us more information. \n\nFirst you'll want to use an event name we can understand, which I'll get back to shortly.\n\nSecond, to help us better detect unusual behaviour, you should send us the User Agent and IP address of the request your user is making. Segment use [a field called Context](https://segment.com/docs/spec/common/#context) to do this:\n\n```\n{\n  \"type\": \"track\",\n  \"userId\": \"11223344\",\n  \"event\": \"Logged In\",\n  \"context\": {\n    \"ip\" : \"1.2.3.4\",\n    \"userAgent\" : \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.112 Safari/537.36\"\n  }\n}\n```\n\nMost server-side frameworks will have an easy way to grab those details. Ruby on Rails has `request.remote_ip` and `request.user_agent`, for example.\n\nFinally, if you want to turn on Was This You notifications, you'll also need to send their email address and / or mobile number with any `log-in` event, as well as [turning on notifications in your API Settings](http://help.thisdata.com/docs/was-this-you-notifications-when-and-where).\n\nYou can send those details within [Segment's `Properties` field](https://segment.com/docs/spec/track/#properties). Here's an example:\n\n```\n{\n  \"type\": \"track\",\n  \"userId\": \"11223344\",\n  \"event\": \"Logged In\",\n  \"properties\": {\n    \"email\" : \"eve.smith:::at:::example.com\",\n    \"mobile\" : \"+64270000001\"\n  },\n  \"context\": {\n    \"ip\" : \"1.2.3.4\",\n    \"userAgent\" : \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.112 Safari/537.36\"\n  }\n}\n```\n\n_Pssst: here's a quirk! Segment have reserved the property called \"name\" for the event's name. So you can't pass your user's name using `\"name\"` in the properties field. You'll need to have used an `identify` call prior to sending an event if you want their name to be properly captured._\n\nIn short, send us some `context` and some `properties`!\n\n### What Segment events will show up in ThisData?\n\nThisData won't slurp up every single event - we'll pick out the important ones. We do this by looking at your event name.\n\nSegment let you specify your own event names, so we're pretty liberal in what we accept too. Here's some examples of how we map possible Segment events to our own events:\n\n- `log-in`: \"login\", \"log-in\", \"LogIn\", \"logged in\", \"signed in\", \"Sign-in\", etc\n    - you send this to Segment when a user logs in\n- `log-in-denied`: same as `log-in`, plus \"deny\", or \"denied\" on the end\n    - you send this to Segment when someone gets a username / password wrong\n- `log-in-challenge`:  same as `log-in`, plus \"challenge\", or \"challenged\" on the end\n    - you send this when you challenge someone attempting to log in with a 2FA code or security question prompt\n- `password-reset`: \"password reset\", \"PasswordReset\", \"password-Reset\", etc\n    - you send this to Segment when your user requests that their password be reset\n\n### What about Identify calls?\n\n[Identify calls](https://segment.com/docs/spec/identify/) are Segment's way of learning about your users, so we'll learn from them too. When you send an Identify event to Segment, we'll create or update your user on our end by looking at the `userId` field, and the `email`, `name`, and `avatar` traits.\n\n\n```\n{\n  \"type\": \"identify\",\n  \"traits\": {\n    \"name\": \"Peter Gibbons\",\n    \"email\": \"peter@initech.com\",\n    \"avatar\": \"https://initech.com/pgibbons.jpg\"\n  },\n  \"userId\": \"97980cfea0067\"\n}\n```\n\nThen, when you send through events like logins, they'll be matched up to the attributes above, giving you a readable Audit log.\n\n\n### What next?\n\nWe've got some guides on how to test out your ThisData setup, trigger test alerts, turn on notifications via email or SMS, and more. Check them out: https://help.thisdata.com\n\nIf you're comfortable writing server side code, you can track more kinds of events by using one of our SDKs (currently Ruby, PHP, and .NET). [Take a look at our code libraries](http://help.thisdata.com/docs/libraries).\n\nYou should also take a look at how to automate security responses by watching for our webhooks; we'll let you know when an account is accessed in a weird way, or the user says their account was compromised. Then you can take steps to automatically shut down unauthorized access, and more. [Learn how to create a security workflow with Alert webhooks](http://help.thisdata.com/docs/create-a-security-workflow-with-thisdatas-alert-webhooks)","excerpt":"","slug":"segment","type":"basic","title":"Segment"}
Industry best practice is to notify your users when their account is accessed in an unusual way. Big guns like Google, Facebook, and Salesforce do it. And if you're already using [Segment](https://segment.com), it'll take 30 seconds for you to do it too! Segment allows you to set up Webhook endpoints so that, as well as having data sent to integrations like Intercom or Mixpanel, it'll also be sent to other websites via their APIs. We've got an endpoint which makes it super easy to integrate ThisData with Segment. Here's how to do it: In ThisData: - [Log in to your ThisData account](https://thisdata.com/sign-in) (or [sign up for free](https://thisdata.com/sign-up)) - Click API Settings - Copy your API key Combine your API key with our webhook endpoint URL like this: `https://api.thisdata.com/v1/segment/receive?api_key=YOUR_API_KEY_HERE` Just switch out `YOUR_API_KEY_HERE` for your real API key. On Segment: - [Log in to Segment](https://segment.com/login) - Go to the "Integrations" tab for the Source you want to track - Find and click on the "Webhooks" integration - Click on "Settings" - In the "Webhook URLs" text box, paste the ThisData webhook URL (including your API key), which you made above - Click "Save Changes" - Click "Enable Integration" - Done! ![The Segment webhook settings panel, with a ThisData webhook URL pasted in](https://thisdata.com/blog/content/images/2016/04/segment_webhook_setting.jpg) Now events you send to Segment will also flow through to your ThisData account. We'll begin monitoring for anomalous behaviour, and when it's spotted, take action. This could be by emailing the user, notifying you, sending a webhook to your app; it's all configurable on your ThisData API Settings page. Congratulations on taking the first steps towards automating your security with ThisData using Segment. Now we'll dive a little deeper in to some more areas to consider. These steps might take another ten minutes to nail. ### Do I need to change my Segment calls? You're off to a great start already, but it's even better if you're able to send us more information. First you'll want to use an event name we can understand, which I'll get back to shortly. Second, to help us better detect unusual behaviour, you should send us the User Agent and IP address of the request your user is making. Segment use [a field called Context](https://segment.com/docs/spec/common/#context) to do this: ``` { "type": "track", "userId": "11223344", "event": "Logged In", "context": { "ip" : "1.2.3.4", "userAgent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.112 Safari/537.36" } } ``` Most server-side frameworks will have an easy way to grab those details. Ruby on Rails has `request.remote_ip` and `request.user_agent`, for example. Finally, if you want to turn on Was This You notifications, you'll also need to send their email address and / or mobile number with any `log-in` event, as well as [turning on notifications in your API Settings](http://help.thisdata.com/docs/was-this-you-notifications-when-and-where). You can send those details within [Segment's `Properties` field](https://segment.com/docs/spec/track/#properties). Here's an example: ``` { "type": "track", "userId": "11223344", "event": "Logged In", "properties": { "email" : "eve.smith@example.com", "mobile" : "+64270000001" }, "context": { "ip" : "1.2.3.4", "userAgent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.112 Safari/537.36" } } ``` _Pssst: here's a quirk! Segment have reserved the property called "name" for the event's name. So you can't pass your user's name using `"name"` in the properties field. You'll need to have used an `identify` call prior to sending an event if you want their name to be properly captured._ In short, send us some `context` and some `properties`! ### What Segment events will show up in ThisData? ThisData won't slurp up every single event - we'll pick out the important ones. We do this by looking at your event name. Segment let you specify your own event names, so we're pretty liberal in what we accept too. Here's some examples of how we map possible Segment events to our own events: - `log-in`: "login", "log-in", "LogIn", "logged in", "signed in", "Sign-in", etc - you send this to Segment when a user logs in - `log-in-denied`: same as `log-in`, plus "deny", or "denied" on the end - you send this to Segment when someone gets a username / password wrong - `log-in-challenge`: same as `log-in`, plus "challenge", or "challenged" on the end - you send this when you challenge someone attempting to log in with a 2FA code or security question prompt - `password-reset`: "password reset", "PasswordReset", "password-Reset", etc - you send this to Segment when your user requests that their password be reset ### What about Identify calls? [Identify calls](https://segment.com/docs/spec/identify/) are Segment's way of learning about your users, so we'll learn from them too. When you send an Identify event to Segment, we'll create or update your user on our end by looking at the `userId` field, and the `email`, `name`, and `avatar` traits. ``` { "type": "identify", "traits": { "name": "Peter Gibbons", "email": "peter@initech.com", "avatar": "https://initech.com/pgibbons.jpg" }, "userId": "97980cfea0067" } ``` Then, when you send through events like logins, they'll be matched up to the attributes above, giving you a readable Audit log. ### What next? We've got some guides on how to test out your ThisData setup, trigger test alerts, turn on notifications via email or SMS, and more. Check them out: https://help.thisdata.com If you're comfortable writing server side code, you can track more kinds of events by using one of our SDKs (currently Ruby, PHP, and .NET). [Take a look at our code libraries](http://help.thisdata.com/docs/libraries). You should also take a look at how to automate security responses by watching for our webhooks; we'll let you know when an account is accessed in a weird way, or the user says their account was compromised. Then you can take steps to automatically shut down unauthorized access, and more. [Learn how to create a security workflow with Alert webhooks](http://help.thisdata.com/docs/create-a-security-workflow-with-thisdatas-alert-webhooks)