Use this guide to prepare your system to receive Conversation Action submissions. It covers the shared connection, security and response requirements.
1. Prepare the receiving address
Create a publicly accessible HTTPS address that accepts POST requests. Each delivery contains one JSON object, sent with Content-Type: application/json; charset=utf-8.
- Address: use a public hostname and a valid, publicly trusted TLS certificate. IP addresses and private or VPN-only endpoints are not supported.
- Redirects: use the final receiving address. Mediabriz does not follow webhook redirects.
- Response time: respond within the configured timeout of 3 to 20 seconds. The default is 10 seconds.
- Network access: deliveries have no static source IP. Verify the signature described in section 2.
Connection limits: OAuth2 client-credentials authentication and mutual TLS are not supported. There are no automatic retries or delivery queues for replaying missed submissions.
2. Verify that requests come from Mediabriz
Every request includes X-Mediabriz-Signature. Verify it even when Authentication is set to None.
- Calculate HMAC-SHA256 using the webhook secret and the original request body bytes, before parsing the JSON.
- Compare the result with the header using a constant-time comparison. The signature is 64 lowercase hexadecimal characters. Reject requests that do not match.
- Use
eventIdto identify duplicate submissions. Retries change the body and signature, so do not use the signature or a body hash for this.
There is no timestamp or delivery-ID header. Content-Length gives the request body size in bytes.
Additional authentication is optional:
| Setting | Header sent |
|---|---|
| None | No additional authentication header. The signature is still sent. |
| Bearer token | Authorization: Bearer YOUR_TOKEN. Replace YOUR_TOKEN with the webhook secret. |
| Custom header | The configured header name, with the webhook secret as its value. |
Use a strong random secret and store it securely. Mediabriz does not display the saved secret again. Rate-limit requests and keep secrets out of logs.
3. Read the delivery data
The tables below describe the shared fields. Fields are present unless stated otherwise; null means the value is unavailable. Within schema version 1, ignore additional fields you do not recognize. Use the action-specific guide for fields that differ.
Submission and action
| Field | Type and presence | Meaning |
|---|---|---|
schemaVersion | number; always | Payload format version. Currently 1. |
eventId | string UUID; always | Unique submission ID. Use it to prevent duplicates; see section 5. |
action | object; always | Configured Conversation Action. |
action.type | string; always | Identifies which action was submitted. Use it to choose how to process the delivery. |
action.actionId | string; always | Stable configured action ID: act_ plus eight hexadecimal characters. |
action.label | string; always | Display label agents see, up to 100 characters. |
organizationId | string; always | Genesys Cloud organization ID. |
conversationId | string; always | Genesys Cloud conversation ID; all zeros in a test delivery. |
Agent and delivery information
| Field | Type and presence | Meaning |
|---|---|---|
metadata | object; always | Submitting agent, delivery time and source. |
metadata.agent | object; always | Agent who approved the submission. |
metadata.agent.id | string; always | Genesys Cloud user ID. |
metadata.agent.name | string or null | Agent display name, or null if unavailable. |
metadata.agent.email | string or null | Agent email, or Genesys Cloud username if no email is set. Null if both are unavailable. Use it to identify the agent in your system. |
metadata.submittedAt | ISO 8601 UTC string; always | Time of this delivery attempt. A retry has a new time even under the same eventId. |
metadata.source | string; always | mediabriz-agent for real submissions; mediabriz-test for Test webhook. |
Customer information
| Field | Type and presence | Meaning |
|---|---|---|
customer | object; always | Customer and channel information. Values other than channelType may be null. Use the action-specific guide for customer matching. |
customer.externalContactId | string or null | Linked Genesys Cloud external contact ID, up to 200 characters. |
customer.name | string or null | Customer display name, up to 200 characters. Null when unavailable or the customer is an anonymous Web Visitor. Follow the specialist guide for email cases. |
customer.channelType | string; always | Lowercase channel name, up to 50 characters; unknown when unavailable. Allow new channel names. |
customer.channelAddress | string or null | Channel address or identifier, up to 200 characters; phone, email or platform ID. Follow the specialist guide for matching. |
customer.customerReference | string or null | The customer's number in your system, up to 200 characters. See the action-specific guide to know when it is supplied. |
Customer matching: do not assume a channel address is a phone number. WhatsApp may provide a business-scoped identifier, and anonymous Web Messaging may provide no address. Accept channel names you do not recognize.
Queue information
| Field | Type and presence | Meaning |
|---|---|---|
queue | object or null; always | The queue that delivered the conversation to the approving agent. After a transfer this is the last queue, not the first. null when there was no queue. |
queue.id | string; when queue is an object | Genesys Cloud queue ID, up to 200 characters. |
queue.name | string or null; when queue is an object | Queue name, up to 200 characters; null when Genesys Cloud does not name the queue. |
4. Read custom-field values
customFields contains key/value pairs. Read them using the keys agreed for your integration.
- All values are strings. Dropdowns send the selected option’s key, not its displayed label.
- Values can be entered by the agent, fixed, hidden or read from Genesys participant data. Genesys values are cut to the field’s maximum length; editable values may have been changed by the agent. Multi-line text retains line breaks.
- Empty optional fields are omitted. A participant-data field uses its fallback if Genesys has no value. If no value remains and the field is required, nothing is delivered; otherwise the field is omitted. If all configured fields are empty, the object is
{}. If no fields are configured,customFieldsis absent.
For field configuration in Mediabriz, see Configure Custom Fields.
5. Respond and avoid duplicate processing
Accept a submission: return HTTP 2xx with JSON such as:
{
"success": true,
"referenceId": "YOUR-RECORD-123",
"message": "optional note"
}referenceIdidentifies the record in your system and helps locate it in Mediabriz Insights. It may also be shown to the agent.messageis optional. The action-specific guide explains whether the agent sees it.
Failed delivery: success: false, HTTP 4xx or 5xx, a redirect, timeout or connection error. An agent may retry even if your system processed the original request.
Prevent duplicates using eventId:
- For an already processed ID, do not process it again. Return success with the original reference.
- Keep processed IDs and their references for at least seven days.
- An unchanged retry keeps its ID. A changed or new submission has a new ID. Follow the action-specific guide for which changes count and any additional duplicate rules.
6. Next step
Follow the next step in the setup guide.
Need help? Contact service@mediabriz.com with your organization ID and the relevant eventId.
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article