Interfaces: WebHooks
Webhooks offer a universal and simple way to trigger an event on one server when an event occurs on another server.
For example, the MAILINGWORK event "Newsletter opt-in successful" passes the opt-in data to a URL on your server. This is done as JSON in the body of the POST request. Internally, WebHooks are also used by our Zapier interface.
Managing WebHooks in emma
You can create, display and delete WebHooks using the emma Webservice (API). Failed WebHooks can be reactivated either via the API or with a click in the triggered system notification.
There are four API functions for managing webhooks. The quickest way to learn how API functions behave is the menu 'Extras ⇒ Interfaces ⇒ Webservice demo'. Fill in the parameters you want and copy the generated sample code into your script.
Function 'CreateWebHook'
The function 'CreateWebHook' connects a MAILINGWORK event with the server URL you want. To do so, you pass three parameters:
- app: any name of the webhook for internal use, which you can also filter on later with 'GetWebHooks'
- event: name of the emma event, which you can also filter on later with 'GetWebHooks'. The following events are currently supported:
▸ optin_finalized: opt-in successful
▸ optout_finalized: opt-out successful
▸ profilemanager_finalized: change of subscriber data sent via profile manager - url: your server URL that receives the JSON data
Function 'GetWebHooks'
The function 'GetWebHooks' shows the properties of all webhooks created. Optionally, you can filter on the properties 'app' and 'event'.
Function 'ActivateWebHook'
The function 'ActivateWebHook' activates a WebHook that was deactivated automatically by the system. This happens when the URL of the WebHook was repeatedly unreachable. Before activating, please make sure that the URL is reachable again.
Pass the optional parameter 'replayEvents=1' if the events that accumulated during the first 5 days after deactivation should be sent afterwards. 'GetWebHooks' returns the current activation status of a webhook in the result parameter 'active'.
Function 'DeleteWebHookById'
The function 'DeleteWebHookById' deletes a WebHook that is no longer needed, or that you want to create again afterwards with changed parameters.
Error handling if the URL is unreachable
If calling a WebHook fails repeatedly because the stored URL is unreachable, the system deactivates this WebHook automatically. At the same time, a system notification is triggered, which you can use to reactivate the WebHook with a click. Before activating, please make sure that the URL is reachable again.
During the first 5 days after deactivation, the system stores incoming events in a buffer. When activating, you can decide whether these events should be sent afterwards.
