How do I integrate Conversation Actions with my organization's system?

When an agent approves a Conversation Action, Mediabriz sends the approved result to your organization's system through a configured HTTPS webhook.

Every delivery includes action.type. Current values include CREATE_ORDER and CREATE_RETURN. Your integration should branch on this field to determine how to process the payload.

Note: Additional action types may be introduced within schema version 1. Ignore unsupported action types rather than causing the integration to fail.

This guide is intended for the IT or integration team responsible for creating the endpoint that receives and processes these submissions.

Nothing is sent to your endpoint until the agent has reviewed and explicitly approved the action.

Payload schema version 1
1. Endpoint requirements

Your organization must provide an HTTPS endpoint that accepts POST requests.

The endpoint must:

• Use HTTPS with a valid, publicly trusted TLS certificate.
• Use a publicly resolvable hostname rather than an IP address.
• Be accessible from the public internet. Private or VPN-only endpoints are not supported.
• Point directly to the final endpoint. Redirects are not followed. 

Mediabriz sends one JSON object per delivery using:

Content-Type: application/json; charset=utf-8

The timeout can be configured between 3 and 20 seconds, with a default of 10 seconds. Your endpoint should respond within the configured timeout. 

Important: Mediabriz deliveries do not originate from a static IP address. Do not use source IP allowlisting as your authentication method. Authenticate requests using the configured secret and Mediabriz signature.

2. Payload

Each approved submission is sent as a single JSON object.

Create Order example:

{
  "schemaVersion": 1,
  "eventId": "9c4f2a7e-5b3d-4e8f-9a1b-2c3d4e5f6a7b",
  "action": {
    "type": "CREATE_ORDER",
    "actionId": "act_8f3a1c2e",
    "label": "Order - Dairy"
  },
  "organizationId": "your-genesys-org-guid",
  "conversationId": "c0ffee00-1111-2222-3333-444455556666",
  "metadata": {
    "agent": {
      "id": "agent-user-guid",
      "name": "Dana Levi",
      "email": "dana.levi@example.com"
    },
    "agentModifiedFields": [
      "items[0].quantity"
    ],
    "submittedAt": "2026-08-29T11:20:33.000Z",
    "source": "mediabriz-agent"
  },
  "customer": {
    "externalContactId": "b1e2c3d4-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
    "name": "David Cohen",
    "channelType": "whatsapp",
    "channelAddress": "15551234567",
    "customerReference": "ERP-CUST-1188"
  },
  "items": [
    {
      "sku": "DAIRY-0042",
      "productName": "Cottage Cheese 5%",
      "quantity": 3,
      "unit": "CASE",
      "originalDescription": "three cases of the blue cottage cheese"
    }
  ],
  "queue": {
    "id": "q-guid",
    "name": "Orders"
  },
  "requestedDeliveryDate": "2026-09-01",
  "purchaseOrderNumber": "PO-2026-0815",
  "notes": "Deliver to the back entrance",
  "customFields": { "requested_outcome": "credit", "sales_rep": "R-42" }
}

In this example, requested_outcome is a Dropdown field and credit is the selected option key.

Payload fields

Return payload

A Create Return action uses the same envelope, customer, queue, notes, customFields, signature, response contract and eventId idempotency as an order. The differences are additive.

Example:

{
  "schemaVersion": 1,
  "eventId": "2b7e1c90-4d5a-4f3b-8e6c-1a2b3c4d5e6f",
  "action": {
    "type": "CREATE_RETURN",
    "actionId": "act_5d2c9b1f",
    "label": "Return - Dairy"
  },
  "organizationId": "your-genesys-org-guid",
  "conversationId": "c0ffee00-1111-2222-3333-444455556666",
  "metadata": {
    "agent": { "id": "agent-user-guid", "name": "Dana Levi", "email": "dana.levi@example.com" },
    "agentModifiedFields": [],
    "submittedAt": "2026-09-13T11:20:33.000Z",
    "source": "mediabriz-agent"
  },
  "customer": {
    "externalContactId": null,
    "name": "David Cohen",
    "channelType": "whatsapp",
    "channelAddress": "15551234567",
    "customerReference": "ERP-CUST-1188"
  },
  "items": [
    {
      "sku": "DAIRY-0001",
      "productName": "Milk 3%",
      "quantity": 2,
      "unit": "CASE",
      "originalDescription": "2 cases of milk 3%",
      "reason": "damaged",
      "reasonText": "packages torn, milk leaked"
    }
  ],
  "queue": null,
  "requestedDeliveryDate": null,
  "purchaseOrderNumber": null,
  "notes": null,
  "reference": "45812",
  "pickupDate": null
}

Return-only fields

requestedDeliveryDate and purchaseOrderNumber are present and null on return deliveries. Every items[].sku is validated against the action's catalog exactly as for orders. The payload carries no resolution field: the supplier decides what the customer receives for the returned goods (credit, replacement, collection) under its return policy. When the customer asks for replacement goods, they are described in notes and in the conversation; they are not added as items and no order delivery is generated for them. To capture the customer's requested outcome, add a custom field to the action and read it from customFields.

Some customer and conversation fields may be null, depending on the information available from the messaging channel. Your integration should be able to process submissions when optional fields are missing. 

Pricing, inventory, promotions, and other commercial calculations are not included. These remain the responsibility of your organization’s system. 

3. Authenticate incoming requests

Every delivery includes:

X-Mediabriz-Signature

The signature is an HMAC-SHA256 of the raw HTTP request body, using the secret configured for the action. Your endpoint should verify the signature before processing the JSON payload. 

You can also configure additional authentication using:

• None: use the Mediabriz signature only.
• Bearer: Mediabriz sends Authorization: Bearer <secret>.
• Custom header: Mediabriz sends the secret using the header name you configure.

The same configured secret is used for the HMAC signature and the optional authentication credential. 

The secret should be a strong random value and stored securely by your organization. The secret entered in Mediabriz is write-only and is not displayed again. 

4. Respond to a submission

For an accepted submission, respond with HTTP 2xx and a JSON response such as:

{
  "success": true,
  "referenceId": "SO-4500123",
  "message": "optional human-readable note"
}

• success: indicates whether your system accepted the submission.
• referenceId: your organization's reference for the submitted action, such as a sales order number, credit note number, or ticket ID.
• message: an optional short message that may be displayed to the agent.

Returning a referenceId is strongly recommended. It allows the record created in your system to be associated with the Mediabriz submission and can be shown to the agent. 

The referenceId is also what administrators use to find a submitted action in the Mediabriz Insights dashboard, so return a value your team can look up in your own system.

A 4xx, 5xx, timeout, connection error, or redirect is treated as a failed delivery. The agent may then retry the submission. 

5. Prevent duplicate submissions

Your endpoint must use eventId as an idempotency key.

If an agent retries the same failed or timed-out submission, Mediabriz sends the same eventId.

If your system has already successfully processed that eventId, do not create another order or return. Return a successful response with the original referenceId. 

This is especially important when a timeout occurs. Your system may have processed the submission even though Mediabriz did not receive the response.

It is recommended to retain processed eventId values and their associated referenceId for at least 7 days. 

6. Customer information and messaging channels

The customer information available in the payload depends on the messaging channel.

For example:

• SMS may provide only a phone number.
• WhatsApp may provide a profile name and channel identifier.
• Web Messaging may have no identified customer information.
• Social channels may provide a platform-specific handle or ID. 

Do not assume that channelAddress is always a telephone number. In particular, some WhatsApp users may be represented by a business-scoped identifier rather than a dialable phone number.

When available, customerReference should be treated as the authoritative customer identifier for your business system. 

7. Test your integration

You can send a test delivery from the Mediabriz Conversation Actions settings, including while the action is still disabled.

The test uses the same delivery process as a real submission, including:

• Endpoint validation.
• Signature.
• Authentication.
• Timeout.
• Payload structure.

The test delivery matches the action's type: a Create Return action sends a return-shaped sample with reason, reasonText, reference and pickupDate. When the action has custom fields, the sample includes customFields with the configured fixed and hidden values and a SAMPLE-<key> placeholder (or the default value) for each field agents fill in, so your endpoint sees every key before go-live. For a Dropdown field, the sample uses a configured option key (the default, or the first option) instead of SAMPLE-<key>.

Test submissions use fictional product information and include:

"source": "mediabriz-test"

Use this value if your endpoint needs to distinguish test deliveries from real submissions. 

After the test, Mediabriz displays the endpoint response information so you can verify that the integration is working correctly.

8. Current limitations

• There is no static source IP for Mediabriz deliveries.
• OAuth2 client-credentials authentication is not currently supported.
• Mutual TLS (mTLS) is not currently supported.
• Mediabriz does not automatically retry failed deliveries. The agent can initiate a retry.
• There is no delivery queue that automatically replays missed submissions later. 
• Custom field values are strings only.

Security recommendations

Always verify the X-Mediabriz-Signature, even when using bearer or custom-header authentication.

Use a dedicated high-entropy secret, store it securely, log and rate-limit requests, and reject requests that fail signature verification. 

For integration assistance, contact service@mediabriz.com and include your organization ID. For delivery issues, also include the relevant eventId.

Related configuration

Create Order and Create Return actions each require a product catalog to complete setup. See How do I prepare and upload a product catalog for a Conversation Action?