Overview

Webhooks are a way for your application to get real-time data from our platform. Instead of making an API call, you can set up a webhook to receive data as it happens.

How Webhooks Work

When a specific event occurs in our system, we'll send a HTTP POST payload to the webhook's configured URL. Webhooks can be used to synchronise data between Mimeeq and external systems or to trigger custom actions in your application.

Setting Up a Webhook

To set up a webhook, follow these steps:

1. Log in to Mimeeq app.
2. Navigate to Settings and look for the Data section.
3. Select Webhooks to open the webhook management page.
4. On the Webhooks page, you'll see an option to create New Webhook. Click on this button and provide the following webhook details:
   • Webhook Name: A unique name for the webhook.
   • Endpoint URL: The URL where you want to receive the webhook payloads.
   • HTTP Auth Header Name and Value: If your endpoint requires authentication, you can provide the header name and value here.
   • Event Types: Select the events for which you want to receive payloads.
5. Click on 'Create' to save the webhook.

Webhook Events

You can configure your webhook to receive data for the following events:

Basket

Event Type	Triggered when...
basket-submitted	... someone submits basket.

Contact

Event Type	Triggered when...
contact-created	... a new contact is created.
contact-updated	... changes are made to an existing contact.
contact-deleted	... a contact is removed.

Company

Event Type	Triggered when...
company-created	... a new company is created.
company-updated	... changes are made to existing company.
company-deleted	... a company is removed.
company-note-created	... a new note is attached to a company's record.
company-note-updated	... an existing note on a company's record is updated.
company-note-deleted	... a note linked to a company is removed.

Payload Format

The payload sent to your webhook URL will be in JSON format and will contain the following fields:

{
  "meta": {
    "webhookId": "WEBH-xxx",
    "eventId": "xxx",
    "eventType": "basket-submitted",
    "eventTimestamp": "2024-03-21T13:46:46Z",
    "entityId": "xxx",
    "version": "1.0"
  },
  "data": {/*specific data for the event*/} 
}

Meta Properties

Meta properties provide basic information about the event that triggered the webhook.

Field	Description
webhookId	The unique identifier of the webhook definition.
eventId	The unique identifier of the sepcific event.
eventType	The type of event that triggered the webhook.
eventTimestamp	The timestamp when the event occurred.
entityId	The unique identifier of the main entity involved in the event.
version	The version of the payload format (currently 1.0).

Authentication

If you need extra layer of security you can define a custom authorization header which will be included in every request sent within the Webhook definition. It allows you to implement your own verification logic, which would filter out any request with missing or invalid authorization header.

For example, if you define a custom header x-webhook-secret with a value my-secret-key in the Webhook definition, the request sent to your endpoint will include the following header:

host: your-endpoint.com
content-type: application/json
content-length: 123
x-webhook-secret: my-secret-key
...

Responding to a Webhook

Your webhook endpoint should return a 2xx response to each webhook event. If the response is different than 2xx, we will retry the delivery. You can check the status of the last delivery attempt on the Webhook definitions list.

caution

Events generated by testing webhooks are not counted as a last attempt.

Retry Policy

Mimeeq ensures that the webhook delivery is reliable. If the original sending attempt fails due to receiving a non-2xx response code or by exceeding a timeout of 10 seconds, we will retry the delivery up to 5 more times: after 15, 60, 225, 900 and 3600 seconds. If all retries are unsuccessful, the event will be marked as failed.

Best Practices

• Security: Always use HTTPS for your webhook endpoint to ensure data privacy and integrity.
• Validation: Validate the payload received from the webhook to ensure it's coming from Mimeeq.
• Asynchronous Processing: If a webhook triggers a long-running process in your system, consider using a processing queue for events and return a 202 Accepted response immediately. As a webhook sender we don't need to know if the event was processed successfully or not. The only important information for us is that the event has been delivered successfully. Processing the event synchronously can lead to timeouts and unnecessary retries.
• Dedupe: Ensure that your system can handle duplicate events. Webhooks are designed to be delivered at least once, so you may receive the same event multiple times.
• Monitoring: Monitor the delivery status of your webhooks to ensure that you're receiving all the events. If you notice a high number of failed deliveries, investigate the cause and take corrective action.