See api-docs Menu

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.

We don’t have an API for setting up the Webhook endpoint subscription yet so you will need to create an Activity > Event Broadcaster via the OneLogin Admin portal.

We recommend that you use the JSON Array format type in your Event Broadcaster configuration.

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 use a service like Request Bin to create a temporary endpoint for capturing the payloads but we strongly recommend that you only do this in a complete dev envrionment. Do not send production events to a public location like this.

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

Postman Collection

Be sure to set Postman-specific environment variables indicated by {{ }}.

Download for the Events API


Have a Question?

Have a how-to question? Seeing a weird error? Ask us about it on StackOverflow.

Found a bug? Submit a support ticket.

Have a product idea or request? Share it with us in our Ideas Portal.