Skip to main content

Events (Callback)

About Signicat events​

Events are our way of letting you know when something happens in one of our services. For example, when a document is signed, or if a change is made to your account, then we create an event.

The Signicat Events service lets you subscribe to events published by Signicat services. Once you subscribe to an event, you will automatically receive information about this event into your system.

For general information about events and how to use the events service, see our Events and webhooks documentation.

What are MobileID events?​

MobileID events are a type of Signicat event that are specific to the MobileID service. For example, a MobileID event is generated when an authentication result is ready.

You can see the full list of supported MobileID event types and what they look like when you create a new subscription in the Signicat Dashboard.

Want to learn more?

To learn how to do this, see the Event types section in the Signicat Events documentation.

How do MobileID events work?​

When an asynchronous operation completes, or when MobileID gets a notification that a device has changed state, MobileID publishes an event with the operation result.

If you have subscribed to the event, then you will automatically receive the result at your specified notification URI. This is often referred to as callback.

You can also get the result back through polling. To learn more about polling, see the When to use polling section below.

The operation result that you receive through the Signicat Events service is the same as the result obtained by polling, but wrapped in a Signicat event object.

The operation result is passed in the eventData field of this object.

When to use callback​

We recommend that you always set up callback for production. This offers the best usability and responsiveness as it has the least amount of latency, and means that you do not need to conduct additional polling calls.

When to use polling​

Regardless of whether callback is set up or not, you can fetch the result of a completed operation from Signicat by polling.

You can do this by running GET API calls, but it should only be reserved for testing and development use.

How to set up callback​

To set up callback for MobileID events, you need to create a new subscription in the Signicat Dashboard for the MobileID events that you would like to receive callback for.

Want to learn more?

To learn how to do this, see the How to add a subscription section in the Signicat Events documentation.

Which events does MobileID publish?​

Operation completed events​

MobileID publishes the following events when an operation is completed:

  • registration.completed
  • authentication.completed
  • signature.completed
  • passport-scan.readid.completed (deprecated)
note

The eventData in the published event is the same object as what would have been returned from a corresponding GET call at the same time.

Device events​

MobileID publishes the following events when triggered by a device action, or when a maintenance operation affects the device.

Account recovery​

When a device performs an account recovery:

  • account-recovery.completed
Account recovery state change​

When an account recovery is added or deleted by an end-user on their device:

  • account-recovery.state.change
Device state change​

When a device is locked or deactivated by an external action:

  • device.state.change
What is an external action?

External actions are actions that are not initiated by a REST call to MobileID.

For example:

  • The device can be locked if the end-user enters an incorrect PIN code too many times in a row.
  • The device can be deactivated by the device SDK.
  • The device can be deactivated by the periodic cleanup job if the device has been inactive for too long, such as one year.

What does a MobileID event look like?​

Want to learn more?

To learn more about this, see the What does an event look like? section in the Signicat Events documentation.

Event data​

The result of the MobileID operation is passed in the event data (eventData) field in a MobileID event. The contents of this field differs depending on what type of MobileID event it is.

Operation completed events​

The event data for operation completed events has the same format as the GET operation response.

For response samples, see the respective endpoints in our MobileID API reference documentation:

Example: Event for a completed registration operation

Click to expand
{
    "id": "13a816b4-f6f3-4424-907c-a95e234155b2",
    "timestamp": "2024-07-02T12:53:13.659Z",
    "eventName": "registration.completed",
    "sender": "mobileid",
    "eventData":
    {
        "riskAttributes":
        {
            "operatingSystemType": "Android",
            "deviceHash": "PUZHJ8MuPVdalrASK/3ozmuK/Z7sAjybJzGV4eaJxvw=",
            "operatingSystemFingerprint": "235425456245",
            "operatingSystemVersion": "2.4.3",
            "deviceModel": "Samsung Galaxy s8",
            "deviceManufacturer": "Manufacturer"
        },
        "accountId": "a-ppge-abcdefeghijklmn12345",
        "transactionId": "a65cdcb1-c6fb-4365-9bd3-de3686c2ad06",
        "state": "COMPLETED",
        "created": "2024-07-02T12:53:13.222Z",
        "completed": "2024-07-02T12:53:13.624Z",
        "device":
        {
            "id": "3d7dfb91-d566-481b-b470-23e783546476",
            "state": "ACTIVE",
            "lastOperationType": "REGISTRATION",
            "lastUsed": "2024-07-02T12:53:13.636Z",
            "created": "2024-07-02T12:53:13.625Z"
        },
        "user":
        {
            "externalRef": "123456789",
            "id": "26266fa0-efe9-428a-9ed8-9506d6b1f5ef",
            "created": "2024-03-18T14:31:36.189Z",
            "lastUsed": "2024-07-02T12:53:13.613Z",
            "state": "ACTIVE"
        },
        "operationProperties":
        {
            "activationCode": "919450",
            "authLevel": "TWO_FACTOR",
            "registrationMode": "REGISTRATION",
            "sessionExpiryTime": "2024-07-02T12:58:13.204Z",
             "activatedAuthenticationMethods": [
              "DEVICE",
              "DEVICE:PIN"
            ]

        }
    },
    "accountId": "a-ppge-abcdefeghijklmn12345",
    "expiresAt": "2024-07-02T12:58:13Z",
    "tags": []
}

Device events​

Account recovery​

The event data for account-recovery.completed events has the same format as the GET operation response.

For response samples, see the respective endpoint in our MobileID API reference documentation:

Example: Event for a completed account recovery operation

Click to expand
{
    "id": "13a816b4-f6f3-4424-907c-a95e234155b2",
    "timestamp": "2024-07-03T09:33:57.342Z",
    "eventName": "account-recovery.completed",
    "sender": "mobileid",
    "eventData":
    {
        "transactionId": "a1a56540-5604-404d-8b42-a61f1589e521",
        "accountId": "a-ppge-abcdefeghijklmn12345",
        "state": "COMPLETED",
        "device":
        {
            "id": "7d084601-d9a7-4b2d-9196-5c1cc009f7bb",
            "state": "ACTIVE",
            "lastOperationType": "REGISTRATION",
            "lastUsed": "2024-07-03T09:33:55.339Z",
            "created": "2024-07-03T09:33:55.316Z"
        },
        "user":
        {
            "externalRef": "123456789",
            "id": "282b8344-c8a7-45f9-8dd1-8c3d39369d78",
            "created": "2024-07-02T07:33:18.436Z",
            "lastUsed": "2024-07-03T09:33:55.294Z",
            "state": "ACTIVE"
        },
        "created": "2024-07-03T09:34:08.000UTC",
        "operationProperties":
        {
            "sessionExpiryTime": "2024-07-03T09:39:08.000UTC",
            "activatedAuthenticationMethods":
            [
                "DEVICE",
                "DEVICE:PIN"
            ]
        },
        "riskAttributes":
        {}
    },
    "accountId": "a-ppge-abcdefeghijklmn12345",
    "expiresAt": "2024-07-03T09:38:57Z",
    "tags":
    []
}

Account recovery state change​

The event data for account-recovery.state.change events has the following fields:

Example: Event for a changed account recovery state

Click to expand
{
  "id": "3cd9aab7-2160-41e6-856a-e140a474c464",
  "timestamp": "2024-07-02T12:40:42.157Z",
  "eventName": "account-recovery.state.change",
  "sender": "mobileid",
  "eventData": {
    "accountId": "a-ppge-abcdefeghijklmn12345",
    "state": "ADDED",
    "device": {
      "id": "40b78c3e-edda-4b0f-8c97-4f3f3d36808f",
      "state": "ACTIVE",
      "lastOperationType": "AUTHENTICATION",
      "lastUsed": "2024-07-02T12:40:28.205Z",
      "created": "2024-07-02T12:39:33.416Z"
    },
    "user": {
      "externalRef": "testuser-Mq1S8I",
      "id": "ef9807bc-9978-45f0-acbb-d651e741648f",
      "created": "2024-07-02T12:39:14.615Z",
      "lastUsed": "2024-07-02T12:40:28.195Z",
      "state": "ACTIVE"
    }
  },
  "accountId": "a-ppge-abcdefeghijklmn12345",
  "expiresAt": "2024-07-02T12:41:12.157Z",
  "isMockEvent": false,
  "tags": []
}

Device state change​

The event data for device.state.change events has the following fields:

Example: Event for a changed device state

Click to expand
{
  "id": "3cd9aab7-2160-41e6-856a-e140a474c464",
  "timestamp": "2024-07-02T12:40:42.157Z",
  "eventName": "device.state.change",
  "sender": "mobileid",
  "eventData": {
    "state": "COMPLETED",
    "device": {
      "id": "40b78c3e-edda-4b0f-8c97-4f3f3d36808f",
      "state": "DELETED",
      "lastOperationType": "SIGNING",
      "lastUsed": "2024-07-02T12:40:28.205Z",
      "created": "2024-07-02T12:39:33.416Z"
    },
    "user": {
      "externalRef": "testuser-Mq1S8I",
      "id": "ef9807bc-9978-45f0-acbb-d651e741648f",
      "created": "2024-07-02T12:39:14.615Z",
      "lastUsed": "2024-07-02T12:40:28.195Z",
      "state": "ACTIVE"
    },
    "triggeredBy": "CLIENT"
  },
  "accountId": "a-ppge-abcdefeghijklmn12345",
  "expiresAt": "2024-07-02T12:41:12.157Z",
  "isMockEvent": false,
  "tags": []
}
Last updated:
On this page