Skip to main content
With a webhook in hellomateo, you can trigger an HTTP POST callback to a configured URL when a specific event occurs within your hellomateo account. The callback payload will contain useful data related to the event. With this data, webhooks can be used to build custom integrations, notifications, and automate other workflows.
  • contact.created: A new contact has been created.
  • contact_details.updated: The contact details have been updated.
  • contact.deleted: A contact has been deleted.
  • conversation.inbound: An inbound message has been received.
  • conversation.outbound: A message has been sent.
  • conversation.submission_error: We are unable to submit the message to the API of the provider.
  • conversation.sending_error: The provider is unable to send the message to the recipient.
  • conversation.tag: A conversation has been tagged.
  • conversation.untag: A tag has been removed from a conversation.
  • conversation.assign: A conversation has been assigned to a user.
  • conversation.unassign: A conversation has been unassigned from a user.
  • conversation.reopen: A conversation has been reopened.
  • conversation.close: A conversation has been closed.
  • form_submission.completed: A form submission has been completed.
  • form_submission.aborted: A form submission has been aborted.
For more information about the events you can trigger a webhook with in Hellomateo, including example payloads, see the webhook event reference documentation.

​
Common webhook use cases

There are various scenarios where webhooks can be useful, some of them include:
  • Building custom chatbots or other workflows
  • Syncing data back into your ERP or CRM system

​
Setting up a webhook in hellomateo

Webhooks can be configured in our Web App and via the hellomateo API. Checkout the Webhook API reference for how to create, list, update, and delete webhooks via the API. To create a webhook in the hellomateo Web App:
  • Go to your Settings > “Integration” > “Webhooks” page.
  • Click “Create”.
  • Add an unique URL for the webhook to send events to. The URL must:
    • Use HTTPS. You can use sites like https://webhook.site or tools like ngrok to create a HTTPS URL to test webhooks locally.
    • Be reachable from the internet, no local hosts.
    • Be able to handle incoming HTTP callbacks.
  • Select the event you want to trigger the webhook for. See the webhook events reference for more information on the events and example response bodies.
  • Add HTTP headers to the webhook. This is optional, but highly recommended as you can add headers like Authorization to secure the webhook.
  • Click “Save webhook”.
  • On the “Webhooks” page, you can see the status of the last sent webhook under each webhook you set up.

​
Handling deliveries

There are a few things to remember when receiving a webhook from hellomateo:
  • You must receive events with an HTTPS server.
  • Your server must quickly respond with a 2xx successful status code to indicate that the webhook was received successfully.
  • Any request is retried up to three times.
  • Hellomateo will not follow any redirects from the server.

​
Responding to webhooks quickly

To protect your service from being overloaded by webhook deliveries, we recommend responding to the webhook request immediately and handling the processing of the webhook asynchronously. Hellomateo will wait a maximum of 2 seconds for a response from your server before marking the webhook as failed.
⌘I