> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axle.insure/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> This guide will walk you through the various events that occur during an Ignition session.

import CustomWebhooks from "/snippets/custom-webhooks.mdx";

Axle’s Ignition session is the main interface that allows your users to connect to their insurance accounts and authorize access to scoped data from their insurance policies.

Please first review the [Quickstart](/guides/quickstart) guide and API docs on how to start an Ignition session, if you have not already.

## Configure an Ignition session for event handling

Your `POST` request to `/ignition` can include the following request
body:

* `redirectUri` (optional) - the URL Axle Ignition will redirect the user to upon completion, exit, or error outcomes of the Ignition session, defaults to no redirect
* `webhookUri` (optional) - the URL Axle will send events to as the user proceeds through the Ignition session, defaults to no webhook events
* `user` (required) - user to attach. Please refer to [startIgnition](/api-reference/ignition/start-ignition) for more details.
* `metadata` (optional) - optional Ignition session metadata, please refer to [startIgnition](/api-reference/ignition/start-ignition) for more details

```bash Request Sample theme={null}
curl --request POST \
  --url https://api.axle.insure/ignition \
  --header 'Content-Type: application/json' \
  --header 'x-client-id: cli_mZj6YGXhQyQnccN97aXbq' \
  --header 'x-client-secret: RZM-5BErZuChKqycbCS1O' \
  --data '{
  "redirectUri": "https://example.com/insurance/redirect",
  "webhookUri": "https://example.com/insurance/webhook",
  "user": {"id": "usr_123456789"}
  }'
```

<Note>
  You can also receive Ignition status updates through the browser Window
  interface. This is most useful when initializing an Ignition session in an
  `iframe` element in your application.

  If you would like to receive
  `MessageEvent` messages to your main application Window from Ignition, you must specify an `origin`
  as a URL parameter when initalizing Ignition. The origin should not include any path, just the base domain as a URI.

  Example: `https://ignition.axle.insure/?origin=http://example.com`
</Note>

## Redirect and Window MessageEvent parameters

On Ignition status change, the following parameters will be shared via URL to the `redirectUri` provided and in the Window `MessageEvent`.

`status`: String

* complete
* exit
* error

**Additional parameters** *(dependent on status, see below)*

* `authCode`: String - authorization code that can be exchange for accessToken for scoped access to connected account and/or policy
* `client`: String - the client ID associated with the session. This is primarily useful for platforms who have multiple clients. See the [Axle for Platforms](/guides/platform-integration) guide for more information about platforms.
* `result`: String - "link" (direct carrier connection was made and policy is available) OR "manual" (policy details were collected via document or form) OR "proxy" (operation was completed on behalf of user)
* `step`: String - the step where the Ignition session was exited
* `message`: String - additional information about the Ignition session error

```text Redirect sample URL theme={null}
  https://example.com/insurance/redirect?status=complete&authCode=cod_LwPJhgxnjinMEPfGYc-XV&client=cli_mZj6YGXhQyQnccN97aXbq&result=link
```

### onComplete

When the user successfully connects to their carrier account and shares authorized access to a selected policy, OR when the user submits their policy information and/or documentation through Axle's manual collection form.

```json theme={null}
{
  "status": "complete",
  "authCode": "<authCode>",
  "client": "<client-id>",
  "result": "link" || "manual" || "proxy"
}
```

### onExit

When the user opts out of connecting to their carrier account and/or selecting a policy, OR when the user opts out of sharing the requested policy information and/or documentation.

```json theme={null}
{
  "status": "exit",
  "step": "<step-name>",
  "client": "<client-id>"
}
```

### onError

When Axle is unable to retrieve account or policy information from a selected carrier, OR when Axle is unable to collect policy information and/or documentation from the user.

```json theme={null}
{
  "status": "error",
  "message": "<message-body>",
  "client": "<client-id>"
}
```

<Warning>
  Never send requests from your client to the Axle API. The client should only
  be used to handle Ignition status through redirect or Window MessageEvent.
</Warning>

## Webhooks

If an optional `webhookUri` is provided, a `POST` request will be sent to the `webhookUri` with the following payload. The individual parameters included within `data` are the same as those listed above for the corresponding status, with the addition of `user` and `metadata` shared via the Ignition request body:

```json Example webhook payload theme={null}
{
  "id": "<event_id>",
  "type": "ignition.completed",
  "data": {
    "client": "<client-id>",
    "token": "ign_Z4ni-JHBvkn9PlKJHPEwk",
    ...{ parameters }
  },
  "createdAt": "2022-10-05T14:48:00.000Z"
}
```

| Type               | Data                                                                                                |
| ------------------ | --------------------------------------------------------------------------------------------------- |
| ignition.created   | client : String, token : String, user: Object, metadata: Object                                     |
| ignition.completed | client : String, token : String, user: Object, metadata: Object, authCode : String, result : String |
| ignition.opened    | client : String, token : String, user: Object, metadata: Object                                     |
| ignition.exited    | client : String, token : String, user: Object, metadata: Object, step : String                      |
| ignition.errored   | client : String, token : String, user: Object, metadata: Object, message : String                   |

<Note>
  <Snippet file="custom-webhooks.mdx" />
</Note>