Webhooks_old

Webhooks

The Merchant API sends a HTTP request, referred to as a webhook message, when specific events are triggered by the customer in the bank environment.

An example of an event is cancellation.requested which specifies that the customer in the bank environment wants to cancel their subscription.

We're constantly adding more events to improve the customer journey and some examples of future events include (but not limited to): pause.requested, resume.requested, upgrade.requested, downgrade.requested, retentionoffer.requested. The use of these events will be illustrated in the respective solution section.

In order to receive requests from Minna, you need to register your endpoint using an API key provided by Minna.

Structure of the webhook request from Minna

A webhook request in general will contain information about which event it is and the data related to it. Every webhook request is structured in the following way:

Request header

Header

Example

Description

Signature

aWduY...dC4=

The message signature is a base64 encoded hash generated with the HMAC SHA256 hash function using the shared secret as key and the payload as the message. See for information about how to verify signature.

User-Agent

minna-webhooks/v1

The user agent and version of the API (v1 in this example).

Content-Type

application/json

All webhooks are in JSON format.

Request payload

Name

Type

Description

id

string

The id of the webhook event.

createdAt

string

The date and time when the event was created. ISO-8601 date-time format. For example 2018-12-03T10:15:30+01:00.

eventType

string

The type of the event.

data

object

The data that will be sent with the event. Differs depending on eventType.

Customer identifiers (for all event types)

Name

Type

Description

id

string

A unique UUID used to identify this event. You may use this in communication with Minna in the future regarding this request.

proof

A market-specific proof or other similar indication that this action was initiated by the user described.

mimeType

Refers to the content type of this proof. Common types are application/xml and application/pdf, but the field is not limited to these content types.

payload

Refers to the data in this proof. If the content type describes binary data, this field will be base64-encoded.

market

Refers to the market this cancellation applies for. Note that due to differences in markets, other fields may differ between markets. Any such differences will be noted under the documentation for the field.

merchantName

Refers to the name of the merchant for which we are sending the webhook request.

name

Refers to the field that contains the name of the user.

emailAddress

Refers to the field that contains the email address of the user.

phoneNumber

Refers to the phone number that is associated with this account, if available. This will be normalized to include country code and other prefixes, e.g. a United Kingdom mobile phone number will be sent on the form +447555123456

customerId

Refers to the ID the user has within your system. This will be on the form that the user inputs when submitting a cancellation.

paymentCardLast4Digits

Refers to the last 4 digits of the credit/debit card that the account was registered with. Note that this is generally provided by the user, and may thus not necessarily match the card that was used for registering the original account, if the user specifies the wrong number.

address

Refers to the information about the user's address. This is, of course, highly market specific.

Payload example (for cancellation event)

{
  "id": "eea6bf1c-0ae9-45af-88be-15a90cb8e708",
  "createdAt": "2018-12-03T10:15:30+01:00",
  "eventType": "cancellation.requested",
  "data": {
    "id": "ffffffff-0ae9-45af-88be-15a90cb8e708",
    "proof": {
      "mimeType": "application/pdf",
      "payload": "VGhlIGNha2UgaXMgYSBsaWU="
    }
    "desiredCancellationDate": "2019-03-03T10:15:30+01:00"
    "market": "UnitedKingdom",
    "merchantName": "ABC Inc.",
    "name": {
      "full": "John Adam Smith",
      "first": "John Adam",
      "last": "Smith"
    },
    "phoneNumber": "+3123456789",
    "customerId": "123456789-4",
    "paymentCardLast4Digits": "1234",
    "address": {
      "street": "Main Street 1",
      "city": "Smallville",
      "postalCode": "90210"
    },
    "emailAddress": "[email protected]"
  }
}

To start receiving your webhook requests from Minna, you'll need to register your endpoint with us. Get in touch with us and we'll hook you up with a test environment.


Did this page help you?