Webhooks provide a powerful way to integrate your applications with the Magine Pro platform. By setting up webhooks, you can receive real-time notifications about important events, enabling you to automate workflows and streamline processes.

Magine Pro adheres to the Standard Webhook guidelines , ensuring consistency and compatibility with industry standards.

What are Webhooks?

Webhooks are HTTP POST requests that Magine Pro sends to your designated endpoints whenever specific events occur within the platform. Examples of events include user created, subscription updates and more!

Prerequisites

To use the webhooks from Magine Pro, the following prerequisites must be met:

• Must be a Magine Pro customer.
• you need to have a publicly accessible endpoint where Magine Pro can send events.
• Assistance from Magine Pro to configure which events should be sent to which URL:s.

Event examples

Here you can see a few examples of the events that are provided. In the other pages you will be able to find out all of the events that are supported.

Type: user.created
When a user is created on the platform, either through the registration flow or using platform API's, an event of type user.created let's you know that it have been created.

Type: monetization.purchased
When a user goes through the purchase flow successfully will generate this event. This event applies both to TVOD and subscriptions and the payload will let you know the Offer that was purchased.

Type: monetization.subscription.renewed
This is an event that will be triggered every time the subscription for a user have been successfully renewed.

Payload

Payload structure

The payload is JSON formatted with the following structure:

• type: a full-stop delimited type associated with the event. The type indicates the type of the event being sent (e.g "user.created"), indicates the schema of the payload (passed in data), and it should be grouped hierarchically.
• timestamp: the timestamp of when the event occurred (not necessarily the same of when it was delivered).
• data: the actual event data associated with the event.

Example

{
  "type": "user.created",
  "timestamp": "2022-11-03T20:26:10.344522Z",
  "data": {
    "userId": "XXXXXXXXXXXXXXXXXXXXXXXXXUSR",
    "name": "John Doe",
    "country": "SE",
    "locale": "sv",
    "email": "[email protected]",
  }
}

Development considerations

When developing for these webhooks you should expect the fields that are available now to be stable but there could be new fields added to the event.

Verification

👍

Webhook verification is optional, but recommended

Webhook verification is optional. To ensure that the webhook comes from Magine Pro and that it's payload wasn't modified during transmission, it's recommended to enable the feature.

How verification works

Magine Pro provides webhook verification based on Hash-based message authentication code(HMAC) aligned with the standard-webhooks specification.

• Signature scheme: HMAC-SHA256
• Signing secret: Random. Between 24 bytes (192 bits) and 64 bytes (512 bits)
• Secret serialization: base64 encoded, prefixed with whsec_ for easy identification.
• Signature identifier: v1

When an event is sent in addition of the payload, there will also be specific webhook headers, those are:

• webhook-id: A unique webhook identifier
• webhook-timestamp: Integer unix timestamp
• webhook-signature: The signature(s) of this event

The webhook-signature header will be a hashed value using signing secret together with the SHA256 algorithm and including the values for webhook-timestamp, webhook-signature and the payload.

How to enable and use verification

When setting up your webhook and enabling verification, you will receive a signing secret that is shared with Magine Pro.

When a webhook event is received, in order to verify that the event comes from Magine Pro and have not been altered with, you should verify the received header webhook-signature. This is how you verify that the received events have not been altered with:

1. Received data

When you receive the webhook you will use the webhook-timestamp, webhook-id and the payload to encode the data. This is how the data can look like:
Received headers

date: Thu, 02 May 2024 13:02:49 GMT
content-length: 217
webhook-id: msg_511c5c4d-d6f4-4706-a978-e6fe8e05afe6 
host: client-api.tvoli.com
webhook-timestamp: 1714654969 
content-type: application/json 
charset=UTF-8
webhook-signature: v1,MUWZoTf7gr/zBndApC3J91/l0YPRMQZSL6f7nVESI7M= 

Received payload (unformatted to not mess with the verification)

{"type":"user.created","timestamp":"2024-05-02T13:02:49.639Z","data":{"userId":"14Q88QSYF5VJXDU5DOU03H449USR","name":"John Doe","country":"GB","locale":"en","email":"[email protected]","emailOptIn":false,"tags":[]}}

2. Combine the data

The content that should be signed should be on the form: msg_id.timestamp.payload

Given the data we received, for us it will be:

msg_511c5c4d-d6f4-4706-a978-e6fe8e05afe6.1714654969.{"type":"user.created","timestamp":"2024-05-02T13:02:49.639Z","data":{"userId":"14Q88QSYF5VJXDU5DOU03H449USR","name":"John Doe","country":"GB","locale":"en","email":"[email protected]","emailOptIn":false,"tags":[]}}

3. Sign the data

The data should now be signed using the SHA256 encoding algorithm together with the signing key.
For the example, the saved key we have is: whsec_1HALgDIEEr4Issn2rC8pq81XaFcs

The prefix of whsec_ should be stripped before signing.

Our resulting signature (including signature header prefix) will be: v1,MUWZoTf7gr/zBndApC3J91/l0YPRMQZSL6f7nVESI7M=

4. Compare the signatures

In the header webhook-signatures there may be a list of signatures, each starting with a prefix of the version. e.g. v1 . Make sure to remove the version prefix and delimiter (e.g. v1,) before verifying the signature.

In our example we had the header: webhook-signature: v1,MUWZoTf7gr/zBndApC3J91/l0YPRMQZSL6f7nVESI7M=

We can then see that the generated signature matches the received signature and know that the webhook came from a legitimate source.

To test and understand the verification even better, this tool is very helpful so you can try it on real data: https://www.standardwebhooks.com/verify

Webhook configuration

The webhooks will be configured in the Magine Pro Console. You can configure which events that should be sent to what URL's and if verification should be enabled or not. If verification is enabled, a signing secret will be generated for you.

Deliverability and reliability

A webhook delivery is considered successful if it was responded to with a 2xx status code (status codes 200-299), and it is considered a failure in any other scenario.

Retries

If an event is not successfully delivered it will be retried following an exponential backoff strategy. The current strategy involves a total of 11 retry attempts spanning over more than 48 hours.