# Event System

# Overview

Online Payments has an event system, which will allow partners to keep their systems "synchronised" in near realtime as transactions are updated.

We communicate events to external partners via HTTP webhook messages, which will contain the details of the alterations that have been made to a transaction.

# Event Types

We currently support two event types:

TransactionUpdated
- This event is triggered when any of the transactions properties have changed
- This event is subject to a delay of up to 3 minutes (see Batch Processing / Flood protection)
TransactionCompleted
- This event is triggered only when a payment is made, which transitions the status of the transaction to "Complete"
- This event will be sent immediately (without delay)

# Event Message Format

An event contains information about a single transaction. There are no instances where a single event contains multiple transactions.

The format of the event message is as follows:

{
  "version": "0",
  "id": "256204c0-05c1-f377-3533-6e52c5e213b3",
  "detail-type": "TransactionUpdated",
  "source": "atg.production.online-payments",
  "account": "239566997751",
  "time": "2023-03-29T09:27:55Z",
  "region": "eu-west-1",
  "resources": [],
  "detail": {
      "ndMeta": {
          "group": "91d302f32e9d6d618a6f91f7096b4aad37d59027",
          "franchise": "041b4a0fc1d1e6e685abac4eb27561e26356ab53",
          "branch": "Mercedes-Benz",
          "location": "496ee710a694d8086edee4916387cc937241680c",
          "groupSoftware": "6800e067fdf5e7bb1838f8333e01e21a8122cfd5"
      },
      "uuid": "314da7b6-e870-5074-92d3-2c9741b9b416-EU01",
      "status": 0,
      "vehicle": {...},
      "customer": {...},
      "valuation": {...},
      "extras": {...},
      "payments": {...},
      "financeProposal": {...},
      "deliveryCollection": {...}
  }
}

# Properties

version

Not used for integration, disregard

Message ID which could be used to prevent duplication

detail-type

Either TransactionUpdated or TransactionCompleted (Event Types)

source

Environment specific source field should be used to prevent accidental pollution when working with multiple environments

Production: atg.production.online-payments

Staging: atg.staging.online-payments

account

Not used for integration, disregard

time

Timestamp of the message being published

region

Not used for integration, disregard

resources

Not used for integration, disregard

detail

The message body, which replicates the response format of the transaction API

# Batch Processing / Flood protection

As a user is progressing through the checkout journey, they are updating their transaction many times in quick succession. Delivering an event notification to our partners for each of these updates would be inefficient and could potentially cause performance issues for the consuming service.

To avoid this issue we have implemented two mechanisms:

Dormant Transactions
- We only process notifications for transactions that have not been updated for two minutes
- This means that at most the consuming service will receive one request per active transaction every two minutes
Batch processing
- Once a transaction has become dormant, we batch all of the updates that have been made to the transaction into a single event, which is delivered to the partner

The message format is always the same, however the "detail" property will only include the elements of the transaction that have been updated.

For example, if a new "extra" has been added and that is the only change, then the detail would be delivered as:

{
  "detail": {
      "ndMeta": {
          "group": "91d302f32e9d6d618a6f91f7096b4aad37d59027",
          "franchise": "041b4a0fc1d1e6e685abac4eb27561e26356ab53",
          "branch": "Mercedes-Benz",
          "location": "496ee710a694d8086edee4916387cc937241680c",
          "groupSoftware": "6800e067fdf5e7bb1838f8333e01e21a8122cfd5"
      },
      "uuid": "314da7b6-e870-5074-92d3-2c9741b9b416-EU01",
      "status": 0,
      "extras": {...}
  }
}

If the transaction was subsequently updated with customer data and a delivery method:

{
  "detail": {
      "ndMeta": {
          "group": "91d302f32e9d6d618a6f91f7096b4aad37d59027",
          "franchise": "041b4a0fc1d1e6e685abac4eb27561e26356ab53",
          "branch": "Mercedes-Benz",
          "location": "496ee710a694d8086edee4916387cc937241680c",
          "groupSoftware": "6800e067fdf5e7bb1838f8333e01e21a8122cfd5"
      },
      "uuid": "314da7b6-e870-5074-92d3-2c9741b9b416-EU01",
      "status": 0,
      "customer": {...},
      "deliveryCollection": {...}
  }
}

# Webhook Endpoint

The partner should provide a webhook endpoint, which we can deliver events to. The endpoint should accept a request matching the following signature:

POST https://your-webhook-endpoint.com/path/here
> X-Webhook-Signature: {To be provided by ATG}

# Signature Verification

The incoming request will have an "X-Webhook-Signature" header, which should match the value that ATG shared with you. Any message that does not provide the expected signature should be discarded.

# Authorization / Permissions

A partner will only receive events for the groups, franchises and locations that they are authorized to access. The scope of the webhooks permissions are tied to the partners API authorization.

In this way, the partner should be able to use their API access to act upon any transaction that they receive.

← Authorization Transactions API →