Webhooks

​

Available Webhooks

​

Requesting Webhooks

• The name of the webhook you wish to use.
• The use case(s) for how and why you’re using the specific webhook.
• Your client ID and the environment type (integration or production) in which the webhook will be installed.
• The target URL.
• If you choose to enhance your security, include the requested information for your respective security type as outlined in Security. (For example, the username and password for HTTP basic authorization.)

​

Managing Requested Webhooks

• The name of the webhook you want to manage.
• The management action (edit, test, or delete).
• For edit requests, include details about the edit you’re making. (For example, an updated callback URL.)

​

Features

• They’re delivered via RESTful HTTPS requests to your listening service.
• They’re triggered when a qualifying event occurs in the MX system.
• They can make requests to any specified URL. (Configuration for this is done offline and out of band.)
• Each POST request includes a JSON-formatted payload.
• The frequency of request retries diminishes over time.

​

Best Practices

• Don’t rely on webhooks as triggers in your UX: Use a postMessage or API request to determine the state of the MX system instead of relying on the receipt of a webhook. If a webhook is being used as a trigger in your UX flow, we recommend putting in a failsafe timer and reading the status from our API as a backup mechanism if a webhook doesn’t arrive in a timely manner. This ensures the end user isn’t left waiting while the UI is waiting for a message that’s sitting in a queue trying to be delivered.
• Respond to webhook requests immediately: It’s crucial to respond promptly to webhook requests, whether with a success or error code, to prevent resource tie-ups for both your system and MX.
• Send a 204 No Content response upon successful receipt of a webhook: This avoids unnecessary resource consumption, crucial for preventing delays in payload processing on both systems.
• Only issue error codes when the webhook wasn’t successfully received: MX payloads may contain null values or include unexpected new fields. If your systems encounter difficulty parsing such situations, issuing an error code won’t resolve the problem as MX will resend the same unexpected payload, resulting in the same error. If your system returns a 429 Too Many Requests error, MX will automatically re-queue the webhook for later delivery. If you have rate limiting implemented, we recommend returning this error instead of a 500-level error.
• Design your webhook payload processing to be resilient to changes: While existing fields won’t be removed, new fields may be added, and the order of fields isn’t guaranteed.
• Put every webhook you receive into an internal queue for processing: This helps you process requests as quickly as your system allows and lets you have your own error retry queue for internal errors. Any webhooks that your system can’t process should be placed in a separate list for examination, where you can log and resolve any errors.
• Ensure proper handling of duplicate webhooks: If you receive a duplicate webhook for a single event, log every event you process and don’t process any event that has already been logged. This practice helps prevent future occurrences of duplicate events.
• Compare revision fields: Object-based webhooks, such as the Members webhook, contain a revision field. The revision number is incremented each time the object is updated on the MX platform. If you’re using object-based webhooks, you can compare the revision field of the payload you just received with that of the object you have previously stored in your database to determine if the payload just received is the most recent one.

​

Changes to Expected Payloads

​

Date and Time Formats

• Fields ending in _at are in Unix epoch time. For example, 1504224000.
• Fields ending in _on are in ISO 8601 format. For example, 2017-09-01.

​

Error Handling

• 200 OK
• 201 CREATED
• 202 ACCEPTED
• 203 NON_AUTHORITATIVE_INFORMATION
• 204 NO_CONTENT
• 205 RESET_CONTENT
• 206 PARTIAL_CONTENT

​

Duplicate Webhooks

​

Fields Ending in _set_by

​

Retries

​

Security

​

HTTP Basic Authorization

​

Mutual Certificate Authentication

• Common name
• Organization
• Department
• City
• State/Province
• Country
• Key size (MX uses the recommended size of RSA-2048)

• It will not expire within 6 months.
• It has been properly installed in your or your data partner’s system and validated by the respective party as behaving correctly.
• If required, it has the correct associated intermediate or trunk and root certificates that are current and will not expire within 6 months.

​

OAuth 2 Access Token Authentication (Client Credentials)

POST /token?grant_type=client_credentials HTTP/1.1
Host: server.example.com
Authorization: Basic YWNtZTo4NTdkM2Y1YWU0ZWNhNjUy
Accept: */*
Content-Length: 0
Date: Tue, 25 Oct 2022 18:38:10 GMT
User-Agent: HTTPClient/1.0 (2.8.3, ruby 2.6.8 (2022-06-27))

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "access_token": "MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
  "expires_in": 3600,
  "token_type": "bearer"
}

POST /token HTTP/1.1
Host: server.example.com
Authorization: Basic YWNtZTo4NTdkM2Y1YWU0ZWNhNjUy
Accept: application/json
Content-Length: 29
Content-Type: application/x-www-form-urlencoded
Date: Tue, 25 Oct 2022 18:35:13 GMT
User-Agent: HTTPClient/1.0 (2.8.3, ruby 2.6.8 (2022-06-27))

grant_type=client_credentials

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "access_token": "MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
  "expires_in": 3600,
  "token_type": "bearer"
}

​

Webhook Timing