Mergado vs. App communication

What is a hook?

Your app communicates with Mergado via our API. In exchange, Mergado also needs to actively communicate with your app.

This is done via web hooks, which Mergado - at certain situations - calls upon your app’s hook endpoints. To be specific, these hooks are HTTP POST requests with certain JSON (content type application/json) payload that specifies the hook’s nature.

Note: By default, all apps are assigned with a hook URL similar to this: https://appcloud.mergado.com/apps/myveryappwow/hook/. You can manage your app’s hook URL via your app’s Storage page in Developers.

Example

Imagine a situation, where an app is being turned off by its user. Typically, the app might have created a bunch of rules, elements and other “soon-to-be-unwanted-garbage” during the time it was enabled. This is one of the typical use cases for hooks - and in our example, it’s up to the developer of the app to clean up this built-up garbage.

What Mergado sends Its meaning What your app should do
{
    "action": "app.disable",
    "entity_id": 42,
    "entity_type": "shop",
    "user_id": 123,
    "user_locale": "sk_SK"
}
Someone disabled your app for shop 42.

Use Mergado API to clean up after your app.

You might want to erase rules, queries, elements, etc. it created during its lifetime. You also might want to make a note that your app no longer needs to run CRON jobs for this e-shop (as it would be pointless to do from now on), etc. Generally speaking, this is the time for cleaning up both Mergado and also your app's database.

Data

The specific data along with a hook are entirely up to the type of the hook that is being called. Thus, any logic that handles a hook should assume data structure based solely on hook’s action field.

{
    "action": "app.enable",
    "entity_id": 42,
    "entity_type": "shop",
    "user_id": 234,
    "user_locale": "cs_CZ"
}

Here, as an example, because the field action contains app.enable, we can now safely assume that data will also contain fields entity_id and entity_type. We know that Mergado is calling this hook because someone enabled your app for e-shop with ID 42.

You can find the list of all hooks along with their possible data fields down below.

Response

A hook is considered properly handled if Mergado receives back a 2xx HTTP response. Hooks returning a 4xx HTTP response are considered to be handled improperly and that can either be evaluated as an error or can be safely ignored by Mergado, based on the nature of the hook. Lastly, a hook is considered to be erroneous when there is 5xx HTTP response and such situations are always considered an error.

Security

Every time Mergado sends a hook, the request will contain a special HTTP header Mergado-Apps-Webhook-Secret with a specific secret string that is unique to each app and each of its envs. This is true for all webhooks and for all app-rule based requests, too.

You can find all of your app’s webhook secret values in Developers.

Warning: Developers are strongly advised to always check the correct value of this HTTP header to secure the app’s hook endpoint against unauthorized access from any malicious third-parties.

List of hooks

Below is the list of currently implemented hooks that can be invoked on your app by Mergado.

ping

A test hook that can be sent from app’s Developers page. This hook is successfully handled when the app returns a HTTP response 2xx and a JSON containing field message with the value of pong.

Hook OK response Error response
{
    "action": "ping"
}
HTTP/1.1 200 OK

{
    "message": "pong"
}
HTTP/1.1 404 Not Found

app.enable

Called when app is being enabled. If this hook is properly handled (i.e. app returns HTTP code 2xx), app is going to be enabled. Otherwise (HTTP codes 4xx or 5xx) the app is not allowed to be enabled. If such cases optional JSON with a message field can be returned and this message will be then reported back to the user (eg. reasons why the app currently cannot be enabled).

Parameters

Example

Hook OK response Error response
{
    "action": "app.enable",
    "entity_id": 42,
    "entity_type": "project",
    "user_id": 666,
    "user_locale": "en_GB"
}
HTTP/1.1 200 OK
HTTP/1.1 400 Bad Request

{
    "message": "E-shop has no Google Analytics access."
}

app.disable

Called when app is being disabled. If this hook is properly handled (i.e. app returns HTTP code 2xx), app is going to be disabled. Otherwise (HTTP codes 4xx or 5xx) the app is not allowed to be disabled. If such cases optional JSON with a message field can be returned and this message will be then reported back to the user (eg. reasons why the app currently cannot be disabled).

Parameters

Example

Hook OK response Error response
{
    "action": "app.enable",
    "entity_id": 42,
    "entity_type": "project",
    "user_id": 666,
    "user_locale": "en_GB"
}
HTTP/1.1 200 OK
HTTP/1.1 500 Bad Request

{
    "message": "Error encountered during cleanup."
}