Skip to main content

Testing and troubleshooting

Testing webhooks on localhost​

To enable rapid development, it's easiest to expose your local development environment to the internet. This allows webhooks to communicate with your local server while you develop the integration.

You can use ngrok, which is free and available for all major operating systems, to expose your local development environment. Download ngrok from their downloads page.

After downloading and installing ngrok, run the appropriate command for your operating system. The command below will expose your local server on port 5432:

Bash

In the output from the command, you should see something like:

Bash

The URL ending in *.ngrok.io should be used when configuring the webhook endpoint URL.

Setting up a webhook​

Webhooks can be set up using the Webhooks configuration page. You will need administrator permissions in order to access this page.

Alternatively, webhooks can be set up using the Webhooks API.

Important configuration fields​

There are several key fields which are important to understand when setting up a webhook:

  • Endpoint URL: The HTTP endpoint URL to which the webhook will send the payload. The payload will be sent using an HTTP POST request and the content-type will be application/json. When testing the webhook locally, you will populate this field with the URL provided by ngrok.

  • SSL Verification: We strongly recommend using HTTPS when setting up your Endpoint URL and keeping this option enabled. However, it is possible to configure the Endpoint URL with an HTTP endpoint or with an HTTPS endpoint with a self-signed SSL certificate which cannot be verified (both of these are not recommended in a production environment). If you are using a self-signed SSL certificate or one which cannot be verified, you have the option of disabling SSL Verification to bypass the certificate verification process.

  • Payload Version: The Payload Version specifies whether the payload objects delivered by the Webhook should use the account's pinned API version ("Pinned") or the latest ("Latest") version available. For production sites it is recommended to select "Pinned". For further information see Webhook Versioning.

  • Secret: The secret ensures that the requests sent to your Endpoint URL are in fact being sent by Mambo. Each request you receive will contain an X-Mambo-Signature header which contains a value signed using the secret. More information can be found in the Secure your webhooks section.

  • Events: The events are what cause a webhook to be triggered and send a request to your Endpoint URL. Each webhook can be triggered by one or more events. The full list of events, when they're fired and the payloads can be found in the Events and payloads section.

  • Sites: The sites field allows you to specify from which sites the webhook should monitor events. When you're testing your webhook endpoints locally, you can create a test site and associate your webhook to that site. That way you can create events to trigger the webhooks without impacting any of your live sites. Once you're ready to move the webhook into production, you can update the site associated to the webhook.