Developer Hub

Our comprehensive guides and documentation will help you to start working with Minna's subscription management services.

Get Started    

Overview

A webhook is a method for your application to receive callbacks from Minna on any changes in the system. Webhooks allows you to receive events (hereinafter called webhook messages) and create notifications for the users in your platform. Minna will send webhook messages on any state updates inside our system, this for example includes status changes on a cancellation or improve order, identification of new subscriptionsubscription - A collection of all the contracts your user has with a specific service providers and new service providerservice provider - A company which offers one or more services to their customerss registered.

In order to consume webhook messages, you register a webhook through the Webhooks API by providing a callback URL and by specifying one or more topics of interest. Alternatively, additional webhooks can also be created to subscribe to different topics. Any registered webhooks can later on be unregistered through the Webhooks API.

Use Cases

There are a few use cases for webhooks and webhook messages. The dominating use case is to use the webhook messages to build a reactive system where you send push notifications to the user as updates happens in the Minna Technologies platform. Additionally, you can use the webhook messages to update state for resources on your side from the Minna platform or for analytical purposes.

Webhook Messages

Webhook messages are grouped into topics that represent subjects of interest such as Cancellation or User. Each topic covers a specific group of events from the Minna Technologies platform, for example, the Insight topic covers all the webhook messages originated from insights.

Each webhook message has the following structure:

{
  "id" : "<webhook_message_id>",
  "webhookId" : "<webhook_id>",
  "topic" : "<webhook_message_topic>",
  "data" : "<webhook_message_data>",
  "type" : "<webhook_message_type>",
  "at" : "2019-10-01T10:31:45+01:00"
}

As previously mentioned, topic corresponds to the topic that you registered the webhook for. The id field is a unique identifier for this specific message, the webhookId is the id of the webhook you registered and the type is to indicate if this is a user related message or for a global resource.

The data field contains the update, which schema depends on the topic and the type field. If the topic is Cancellation, then the data field will contain a Cancellation object, and respectively for the other topics.

📘

Note, your callback URL should accept a list of webhook messages.

Security

The webhook callback URL is required to support TLS with minimum version 1.2 for the connection. Older versions will not be accepted.

When registering a webhook, you must provide a signing key. We recommend the key to be 4096-bit. Minna Technologies will use the key to sign every webhook message using HMAC (hash-based message authentication). You can use this to verify that the webhook message originated from Minna Technologies, and not from a different third-party.

A signature is created using HMAC with SHA-2 as hash function, the message is the entire HTTP message body and the signing key as key. For every request you should verify that the value in the HTTP header Minna-Signature (base64 encoded) matches the signature you compute.

For protection against replay attacks we include the property at with the date time for the request in ISO8601 format. This value should be verified with a recommended 30 seconds tolerance (over and under).

Error Handling

Failed request will be retried 20 times with a back off algorithm between each retry over the span of 7 days. Bear in mind that due to the hierarchical organization of webhook messages into topics, and the ability to register a webhook for more than one topic, we might send multiple webhook messages simultaneously.

Minna regards the following cases as errors:

  • Timeout (5 seconds)
  • Non 2xx response status code

If we haven’t received a successful response after 20 retry attempts or if the response is considered within the don't-retry cases, the webhook message will be discarded.

For the following status codes, we will not retry to send the message and discard it instead:

  • 403, 410, 413 and 429 response status codes

Updated about a year ago


What's Next

API reference

Webhooks


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.