1. Home >
2. API >
3. 1 >
4. Events >
5. Event Webhooks

Event Webhooks

Webhooks provide a way to make event driven decisions in your application.

The OneLogin Event Webhook API which is also known as the Event Broadcaster will send batches of events in near real-time to an endpoint that you specify.

All possible Event Types are sent in the payload so you will need to filter out the events that you are interested in. Use the Event Types API to get a complete list of possible types.

Webhook Payload

An array of Event objects is sent to your registered endpoint as a POST request.

This is a example of a bare bones Login event.

[
  {
    "create": {
      "_id": "d210df80-ede8-42ba-8199-00ce951bc222"
    },
    "error_description": null,
    "login_name": null,
    "app_name": null,
    "authentication_factor_description": null,
    "certificate_name": null,
    "certificate_id": null,
    "event_timestamp": "2017-12-05 19:13:06 UTC",
    "assumed_by_superadmin_or_reseller": null,
    "directory_name": null,
    "actor_user_id": 32916209,
    "user_name": "John Richards",
    "mapping_id": null,
    "radius_config_id": null,
    "risk_score": null,
    "otp_device_id": null,
    "imported_user_id": null,
    "resolution": null,
    "directory_id": null,
    "authentication_factor_id": null,
    "param": null,
    "risk_cookie_id": null,
    "app_id": null,
    "custom_message": null,
    "browser_fingerprint": null,
    "actor_system": "",
    "uuid": "d210df80-ede8-42ba-8199-00ce951bc222",
    "otp_device_name": null,
    "actor_user_name": "John Richards",
    "user_field_name": null,
    "assuming_acting_user_id": null,
    "adc_id": null,
    "solved": null,
    "api_credential_name": null,
    "imported_user_name": null,
    "note_title": null,
    "trusted_idp_name": null,
    "policy_id": null,
    "role_name": null,
    "service_directory_id": null,
    "object_id": null,
    "account_id": 92920,
    "user_field_id": null,
    "resolved_by_user_id": null,
    "group_id": null,
    "client_id": null,
    "ipaddr": "125.236.219.21",
    "login_id": null,
    "notes": "Authentication method: password.",
    "event_type_id": 5,
    "user_id": 32916209,
    "risk_reasons": null,
    "proxy_agent_name": null,
    "policy_type": null,
    "role_id": null,
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.94 Safari/537.36",
    "privilege_name": null,
    "group_name": null,
    "entity": null,
    "resource_type_id": null,
    "resolved_at": null,
    "note_id": null,
    "mapping_name": null,
    "task_name": null,
    "authentication_factor_type": null,
    "proxy_agent_id": null,
    "adc_name": null,
    "radius_config_name": null,
    "policy_name": null,
    "trusted_idp_id": null,
    "privilege_id": null,
    "proxy_ip": null,
    "directory_sync_run_id": null
  }
]

How to Respond

On successful receipt of the webhook payload your endpoint must respond with an HTTP 200 status code.

If a non 200 code is returned or a timeout occurs then the webhook payload will be sent to your endpoint again. This process will be repeated for a maximum of 3 attempts and then will not be sent again.

Using Custom Headers

When configuring your Event Broadcaster via the OneLogin Admin Portal you have the opportunity to specify custom headers that will be sent along with each request.

A great way to add additional security and verify the authenticity of the request would be to set an abitrary string as a custom header value and ensure that the same string is sent with each webhook payload.

Filtering Events

The events webhook endpoint is a firehose of every event that occurs on your OneLogin account.

This is useful if you are streaming the events into a SIEM or logging system but it’s also likely that you might just want to respond to certain events like a high risk login.

The best way to start filtering events is by event_type_id. e.g. Do something with events that have an event_type_id=5 and risk_score>50.

You can get a complete list of event types from the Event Types API but here are a few popular ones.

• 5 - User Login Success
• 6 - User Login Failed
• 7 - User Logout
• 8 - User Logged into an App
• 11 - User Changed Password
• 22 - User Added an MFA Device

Sample Code

To receive a webhook payload you simply need to create an endpoint that is capable of accepting a POST request.

You could also use one of the sample code repositories that we have made available on Github.

• Ruby - Event Broadcast Receiver
• Node.js - A Serverless AWS Lambda that sends risky events to a Slack channel

Postman Collection

Clicking Run in Postman button navigates to the page where you can fork the collection to your workspace. Forking the collection into your workspace will enable you to contribute to the source collection using pull requests. You can also view the collection in a public workspace if you like and even import a copy of the collection using the links present on the screen.

---