Overview

The Merchant API sends a webhook message when specific events are triggered in our system. Refer to each of the sections on the left to get a list of all the webhook events covered within.

Webhook requests

A webhook request in general will contain information about which event it is and the data related to it. All requests should be verified. You can read more about how to verify the signature here.

Request headers

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<uuid>

The id of the webhook event.

createdAt

string<date-time>

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.

Payload example

{
  "id": "eea6bf1c-0ae9-45af-88be-15a90cb8e708",
  "createdAt": "2018-12-03T10:15:30+01:00",
  "eventType": "cancellation.requested",
  "data": {...}
}

🚧

Note:

This message will not be shown to the user and is to be used for communicating and debugging between Minna and the merchant.

Responses
UserNotFound

Returned if a user could not be found with the information that was given.

InconsistentData

Returned if the user's data does not match what you have on file. Use this if e.g. the credit card digits do not match the name of the user, or other similar issues.

AlreadyCancelled

The user's contract was already cancelled. The date on which this previous cancellation took effect needs to be provided.

BindingPeriod

The user's contract is bound and cannot be cancelled until the specified date.

Examples
code: 404
payload: {
  outcome: "UserNotFound",
  statusMessage: "Sorry, we could not find you in our system."
}
code: 404
payload: {
  outcome: "InconsistentData",
  statusMessage: "Sorry, the information you provided with your cancellation does not match the information in our systems."
}
code: 404
payload: {
  outcome: "AlreadyCancelled",
  cancellationDate: "2019-03-03T00:00:00+00:00"
  statusMessage: "Your subscription was already cancelled."
}
code: 404
payload: {
  outcome: "BindingPeriod",
  cancellationDate: "2019-03-03T00:00:00+00:00"
  statusMessage: "Your subscription cannot be cancelled until March 3 2019."
}

API Reference

You can find the API reference for managing webhooks here.


Did this page help you?