What are Webhooks?
Webhooks allow you to receive programmatic notifications from MoonBack about changes that occur to your MoonBacks as they happen in real time. If you are new to using webhooks, read this guide for more information.
Instead of you having to retrieve information through our API, webhooks send information about events that occur in your account. When one of these events is triggered (for example, when a new MoonBack is created), we send that notification as an HTTP POST request with a JSON body to the URL you specify.
You can easily create a webhook from the Integrations page. You will find links to several webhooks test environment platforms so you can test how they work before integrating them into your system.
Once you've tested it, you just need to define two parameters:
Webhook URL.
It is the URL receiving the requests of events via POST. We recommend to use https protocol for security reasons. In all our requests, we include two headers for security, so you can be sure that we are the ones calling this URL:
signature: {hash_hmac_sha256_paypload}
moonbacker-signature: 99d7860a23496bb18ccde0dcb584a6be
agent: MoonBack-Webhook-Agent
moonback-webhook-server-version: 2.1
hash_hmac_sha256_paypload is generated, as usual, as a hmac sha256 depending on the payload and the secret defined in your settings.
$payloadJson = json_encode($payload);
$signature = hash_hmac('sha256', $payloadJson, $secret);
NOTE: The moonback-signature code in this document is incorrect, each account has its own and you can verify this number in the integration page of your MoonBack account.
When a webhook call fails, we'll retry the call 3 more times. To not hammer the remote app we'll wait some time between each attempt. By default, we wait 10 seconds between the first and second attempt, and 100 seconds between the second and the third attempt.
The events
Simply define the events you want to subscribe to. Once an event is triggered, we will perform a call to the Webhook URL with the MoonBack information and information about that event.
The events currently available are the following (event code and explanation):
References to User and Authentication:
- USER_LOGIN: User login to MoonBack.
- USER_RECOVER: Retrieve the requested password.
- USER_LOGOUT: Exit of the user from MoonBack.
References to the administration of a MoonBack:
- MB_CREATED: MoonBack created
- MB_EDITED: MoonBack edited
- MB_CLONED: MoonBack duplicated
- MB_DELETED: MoonBack deleted
- MB_READY: MoonBack converted
- MB_UNDELETED: MoonBack restored
References to starting a MoonBack:
- MB_LAUNCH_LINK: Start MoonBack via link
- MB_LAUNCH_EMAIL: Start MoonBack via e-mail
- MB_LAUNCH_WEB: Start MoonBack via Internet
- MB_LAUNCH_QR: Start MoonBack via QR
- MB_LAUNCH_WHATSAPP : Start MoonBack via Whatsapp
- MB_LAUNCH_TELEGRAM: Launch MoonBack via Telegram
References to interacting with a MoonBack:
- MB_ACCESS: Access MoonBack
- MB_PLAY: Play MoonBack
- MB_LINK_CLICK: Link clicked in MoonBack
- MB_REACTION: Reaction in MoonBack
- MB_REPLY: Reaction in MoonBack
- MB_REPLY_READY: Converted MoonBack response
- MB_PLAY_COMPLETED: Playback of MoonBack completed
Example of use
We show you an example of the information received in a Webhook, in this case a MB_REPLY_READY, which is when someone has responded to a MoonBack and it has been converted and is ready for use.
We could for example with this data, use the transcript of what is said in the video, the metrics of the video or the geographic information of the user to be able to program actions in another system.
It is always a code in JSON format where, in blocks, the information relevant to both the MoonBack and the action that has been triggered appears.
{
"data": {
"moonback": {
"code": "f2a1fqs791",
"public_url": "https://moonback.show/f2a1fqs791",
"mid": null,
"message": "Me encantaría formar parte de tu comunidad",
"links": 0,
"notes": "Notas privadas del MoonBack",
"length": 45,
"transcription": "Esto es un MoonBack de prueba con el que quiero conquistarte.",
"url_sd": "https://storage.googleapis.com/moonback/354d9be382b5376ea29a892d4d6475e8/35439be382b5376ea29a892d4d6475e8-Moonback-2021314-f2a1fqs791_low.mp4",
"url_hd": "https://storage.googleapis.com/moonback/354d9be382b5376ea29a892d4d6475e8/35439be382b5376ea29a892d4d6475e8-Moonback-2021314-f2a1fqs791.mp4",
"url_gif": "https://storage.googleapis.com/moonback/354d9be382b5376ea29a892d4d6475e8/35439be382b5376ea29a892d4d6475e8-Moonback-2021314-f2a1fqs791.gif",
"url_jpg": "https://storage.googleapis.com/moonback/354d9be382b5376ea29a892d4d6475e8/35439be382b5376ea29a892d4d6475e8-Moonback-2021314-f2a1fqs791.jpg",
"created_at": 1618385146
},
"metrics": {
"global": 75,
"detail": {
"Awareness": 43,
"Commitment": 23,
"Emotion": 2,
"Conversion": 99,
"Engagement": 12
}
},
"visitor": {
"ip": "82.174.5.113",
"country": "ES",
"city": “Madrid”,
"latitude": 42.750999,
"longitude": -0.821999,
"user_agent": "LinkedInBot/1.0 (compatible; Mozilla/5.0; Apache-HttpClient +http://www.linkedin.com)",
"user_agent_type": "desktop",
"is_bot": true,
"custom_id": null,
"created_at": 1618385297
}
},
"action": {
"name": "Respuesta a MoonBack convertida",
"code": "MB_REPLY_READY"
},
"timestamp": 1618389169
}
Note: The data shown in this example are dummy data. When you perform a test mailing, we will send you the real data from your last MoonBack as an example.
Retry Policy
Webhooks' retry policy is as follows:
In the event that the original notification delivery attempt fails (due to receiving a response code other than 2XX or exceeding the 10-second timeout), we will try 3 more times: at 3, 30, and 150 seconds. If it continues to fail on each of those attempts, it is counted as an unsuccessful delivery.
If there are no successful deliveries in 3 consecutive days, we will delete this specific webhook.
Webhooks Policy
The webhooks policy applies to both general and application-specific webhooks.
MoonBack has a ban system for webhooks, which means that each time the original notification sending attempt fails on the first attempt (due to receiving a non-2xx response code or exceeding a 10 second timeout) a ban counter will increase by one. When the counter reaches 10 on a webhook, this specific webhook will be banned for 30 minutes. When the ban time is over, the webhook is reactivated and the ban counter returns to zero.
Note that if a webhook is unreachable on the first attempt, its ban count will be incremented and then the standard retry logic will be applied, but if the webhook is unreachable during retries, the ban counter will not be incremented.
If there are no successful deliveries to a webhook in 3 consecutive days, we will delete it.