Mobile Journeys Webhooks

Mobile Journeys provides webhooks for events triggered by different actions in the Journey. This page describes the specific webhooks Mobile Journeys supports. These can be subscribed to via the Webhooks API, see the Webhooks documentation for managing your subscriptions.

Guidance for integrating with Mobile Journey webhooks:

The events can be delivered in any order.
Events will be delivered at least once. However, it is possible that events are delivered multiple times.
The order of fields on an event can change.
Additional fields on an event are not considered a breaking change. This prevents excessive version changes.

Standard Data

When your application receives a webhook it will receive an array containing one or more events. The following is the standard webhook structure for a Mobile Journeys event:

{
    "productId": "mobilejourneys",
    "eventId": "eventname",
    "eventVersion": "1",
    "eventTime": "2021-06-11T12:01:45Z",
    "data": {
        "occurredAt": "2021-06-11T12:01:35Z",
        "journeyId": "2",
        "correlationId": "91daa348-0eb0-4062-b4b6-61fd467562b0",
        "customerReference": "AX-123456",
        "sessionId": "654321"
    }
}

productId - This will always be 'mobilejourneys' for these events.
eventId - The specific event type.
eventVersion - Provides the version number of the event. This is used to enable migrations between versions of events when needed.
eventTime - Time of processing event, this may be slightly later than the time the actual activity took place.
data - Contains the custom structure for each event type - see specifics for each event in the sections below. The following are standard fields included in the Mobile Journey events:
- journeyId - Id for the Journey the activity took place against.
- correlationId - Unique identifier for a specific instance/link. This helps associate all events for a given instance/link.
- customerReference - Customer reference associated to the instance/link (not guaranteed to be unique - this is based on the data provided).
- sessionId - When an event relates to a session the session ID will be provided.
- See specific event type below for details of any additional fields.

Link Created

Triggers when a link is created via calling the Mobile Journeys API, and for any instances created by Esendex (this may be happen occasionally for testing and verifying the Journey).

{
    "productId": "mobilejourneys",
    "eventId": "linkcreated",
    "eventVersion": "1",
    "eventTime": "2021-06-11T11:58:11Z",
    "data": {
        "occurredAt": "2021-06-11T11:57:35Z",
        "journeyId": "2",
        "correlationId": "91daa348-0eb0-4062-b4b6-61fd467562b0",
        "customerReference": "AX-123456",
        "url": "https://examplelink.com/CompanyName_abc",
        "parameters": {
            "accountReference": "AX123456",
            "balance": "18.56",
            "name": "Mr Smith",
        }
    }
}

In addition to the standard data fields the following are provided:

url - Fully qualified URL for the instance/link.
parameters - Parameters provided to customise the Mobile Journey for the individual recipient/link.

Session Created

Triggers when a link is clicked which results in the Journey being accessed and a session is created. A link may get multiple sessions as a user may visit multiple times, or it may be a shared link. Sessions can also be created due to previews by applications prior to a user clicking on a link.

{
    "productId": "mobilejourneys",
    "eventId": "sessioncreated",
    "eventVersion": "1",
    "eventTime": "2021-06-11T12:01:45Z",
    "data": {
        "occurredAt": "2021-06-11T12:01:35Z",
        "journeyId": "2",
        "correlationId": "91daa348-0eb0-4062-b4b6-61fd467562b0",
        "customerReference": "AX-123456",
        "sessionId": "654321"
    }
}

This event only provides the standard data fields.

Payment Attempt

Triggers when a payment has been attempted by the user and indicates whether the payment transaction was successful or not.

{
    "productId": "mobilejourneys",
    "eventId": "paymentattempt",
    "eventVersion": "1",
    "eventTime": "2021-06-11T12:01:45Z",
    "data": {
        "occurredAt": "2021-06-11T12:01:35Z",
        "journeyId": "2",
        "correlationId": "91daa348-0eb0-4062-b4b6-61fd467562b0",
        "customerReference": "AX-123456",
        "sessionId": "654321",
        "paymentDetail": {
            "transactionId": "664855f2-076b-448b-8058-41a72ee9608f",
            "transactionTime": "2020-11-27T13:46:31Z",
            "authorised": "true",
            "amount": 5.56,
            "currency": "GBP",
            "cardNumber": "001",
            "authorisationCode": "test/4321",
            "cardType": "DEBIT",
            "cardholderName": "John Smith"
        }
    }
}

In addition to the standard data fields the following are provided under a paymentDetail section:

transactionId - Unique identifier for the transaction.
transactionTime - Actual time the transaction was processed.
authorised - Indicates if the transaction was authorised or not.
amount - Value of the transaction (decimal).
currency - ISO 4217 standard currency code.
cardNumber - Last four digits of the card number.
authorisationCode - Authorisation code for the transaction - only present if the transaction was authorised.
cardType - Indicates if the card is debit or credit, if known.
cardholderName - Name on card.

Document Generated

Triggers when a user clicks the generate option for a document and has initiated their access to the associated document.

{
    "productId": "mobilejourneys",
    "eventId": "documentgenerated",
    "eventVersion": "1",
    "eventTime": "2021-06-11T12:01:45Z",
    "data": {
        "occurredAt": "2021-06-11T12:01:35Z",
        "journeyId": "2",
        "correlationId": "91daa348-0eb0-4062-b4b6-61fd467562b0",
        "customerReference": "AX-123456",
        "sessionId": "654321",
        "templateId": "cf80f9b3-22da-42d9-94a0-285518264677",
        "documentId": "77a3b1e3-cdec-40ca-9543-7685a24120c6",
        "documentCategory": "Invoice-Type1"
    }
}

In addition to the standard data fields the following are provided:

templateId - Identifies the template used to generate the document. If the Journey supports multiple version of a document this can be used to determine which format was used.
documentId - Unique identifier for the generated document.
documentCategory - If the Journey supports multiple documents this can be used to determine the type of document the user generated.

Stage

Triggers when a user submits a page that is configured as a ‘stage event’. What stages are available depends on the individual Journey and are typically used for tracking key progress within a Journey or important data capture points. These are configurable so talk to your Account Manager if you need an additional stage configured.

{
    "productId": "mobilejourneys",
    "eventId": "stage",
    "eventVersion": "1",
    "eventTime": "2021-06-11T12:01:45Z",
    "data": {
        "occurredAt": "2021-06-11T12:01:35Z",
        "journeyId": "2",
        "correlationId": "91daa348-0eb0-4062-b4b6-61fd467562b0",
        "customerReference": "AX-123456",
        "sessionId": "654321",
        "stageName": "journeyEnd",
        "generatedDocumentIds": [
            "cf80f9b3-22da-42d9-94a0-285518264677",
            "77a3b1e3-cdec-40ca-9543-7685a24120c6"
        ],
        "downloadedDocumentIds": [
            "77a3b1e3-cdec-40ca-9543-7685a24120c6"
        ],
        "uploadedDocumentIds": [
            "772dc40f-ae5a-487b-b9a2-372918dc8ae3"
        ],
        "transactionIds": [
            "664855f2-076b-448b-8058-41a72ee9608f"
        ],
        "sessionData": {
            "accountReference": "123456",
            "balance": "13.00",
            "name": "Mr Smith",
            "dateOfBirth": "01-01-1980",
            "addressLine1": "1 Somewhere Place",
            "addressLine2": "A Town",
            "addressLine3": "",
            "addressCity": "A City",
            "postcode": "AA1 1AA",
            "portalName": "DemoPortal"
        }
    }
}

In addition to the standard data fields the following are provided:

stageName - If the Journey supports multiple stage events this can be used to identify the specific stage that has been reached.
generatedDocumentIds - List of all generated document Ids. Can be used to synchronise data between events, especially as the order of events is not guaranteed.
downloadedDocumentIds - List of all downloaded document Ids. Can be used to synchronise data between events, especially as the order of events is not guaranteed. Note: document download events are not yet supported.
uploadedDocumentIds - List of all uploaded document Ids. Can be used to synchronise data between events, especially as the order of events is not guaranteed.
transactionIds - List of all transaction Ids. Can be used to synchronise data between events, especially as the order of events is not guaranteed.
sessionData - Data available on the session at the time this stage event is triggered. This is a combination of any original parameters on the link, entered and processed data that has been recorded within the session. The data may not be the same as originally entered if values have been replaced as a result of formatting or calculations.