Custom Webhook

Configure a Custom Webhook integration to send contact events to your endpoint and send response messages back into active SMS or WhatsApp chats.

A webhook is an HTTP callback request sent to an external application when an event occurs. In the Custom Webhook integration, the platform sends event payloads to the webhook URL you configure.

A webhook HTTP request includes:

• A start line with the HTTP method and URL
• Headers
• A body, also called the payload

Before you start

1. Prepare the endpoint URL that will receive webhook events.
2. Configure your endpoint to accept JSON payloads.
3. Choose the HTTP method your endpoint supports. The platform supports POST, GET, PUT, and DELETE.
4. Choose the authentication type your endpoint requires: API Key, Basic, Bearer Token, or No Authentication.

Create the Custom Webhook integration

1. Select the Custom Webhook card from the integrations pane.
2. Select Next.

The platform opens the Custom Webhook integration window.

Configure the integration in two sections:

• Custom Webhook Information: Defines the webhook alias, request method, URL, parameters, authentication, headers, and body.
• Connections: Defines the platform communication channels used by the integration.

Configure Custom Webhook Information

Use the Custom Webhook Information section to define how the platform sends requests to your webhook endpoint.

Add an alias

Enter an Alias that identifies the Custom Webhook integration in the platform.

Set the method and URL

Select the HTTP method your endpoint supports, then enter the endpoint URL.

Use this URL structure:

METHOD https://Your_Domain/Your_Path

METHOD must be one of the supported HTTP methods: POST, GET, PUT, or DELETE.

Configure request components

The Custom Webhook request has four configurable components:

• Params
• Auth
• Headers
• Body

Params

URL parameters, also known as query parameters, are key-value pairs appended to the end of a URL. They appear after a question mark (?). Multiple query parameters are separated by an ampersand (&).

A URL with query parameters uses this format:

https://www.elipackage.com/items?colour=blue&sort=newest

To add query parameters:

1. Open the Query Params tab.
2. Select Add Field.
3. In the Key column, enter the parameter name.
4. In the Value column, enter the parameter value.
5. In the Type column, select Text or Variable, depending on the information you want to receive in your webhook.

Auth

Authentication secures webhook requests sent to destination systems. Use the Auth tab to choose the authentication type your webhook endpoint requires.

The platform supports these authentication types:

• API Key
• Basic
• Bearer Token
• No Authentication

To configure authentication:

1. Open the Auth tab.
2. Select the Type dropdown.
3. Select the authentication type your webhook requires.

If your webhook does not require authentication, select No Authentication.

Headers

Headers provide metadata for the webhook HTTP request. You can use default headers or add custom headers that the platform sends with the payload.

Common default headers include:

• Content-Type: Describes the data sent in the body, such as application/json.
• Content-Length: Defines the request size in bytes.

To add custom headers:

1. Open the Headers tab.
2. Select Add Field.
3. In the Key column, enter the header name.
4. In the Value column, enter the header value.
5. In the Type column, select Text or Variable, depending on the information you want to send.

You can remove a header by selecting the Delete icon in the Actions column.

The following example shows header key-value pairs sent with all requests:

Body

The body contains the JSON payload sent to your callback URL. The payload includes events recorded when end users participate in your automation.

To receive additional parameters in your webhook:

1. Select Add Field.
2. In the Key column, enter the parameter name.
3. In the Type column, select Variable.
4. In the Value column, choose the variable to send.

For example, to receive the channel where the interaction occurred:

1. In the Key column, enter channel.
2. In the Type column, select Variable.
3. In the Value column, choose {{channel}}.

To exclude a predefined parameter from your webhook body, select the Delete icon in the Actions column.

Configure connections

Use Connections to select the platform channels used for Custom Webhook interactions.

You can add these channel connection types:

• SMS texting
• WhatsApp

Additional channels may be added in future releases.

To configure channel connections:

1. Select a connection from the Available Connections dropdown.

   The left side of the connection shows the channel type. The right side shows the connection code.

   

2. Select Add +.

3. Repeat these steps for each channel that is part of the integration.

The platform adds the selected channels to the table below the menu.

After you define Custom Webhook Information and Connections, select Save.

If you are integrating Custom Webhook with a Chatbot Service automation, complete the required Custom Webhook Information fields without adding connections, then select Save.

Activate a Custom Webhook with connections

After you save the integration, the platform displays it as a card under the Integrations tab. The card shows the alias, URL, integration ID, connection details, API details, and actions to delete, edit, or activate the integration.

To activate the integration:

1. Select Start ▶.
2. Confirm that the integration card changes to the active state.

When the integration is active, the connection icons appear in blue.

To view sender details, select the Details icon on the card. The Connection Details tab shows the channel and number or code associated with each sender.

To view API details, select the API Details tab. This tab shows the endpoint URL, headers, parameters, and responses.

Use the Try Out tab to send response events to chats initialized by a contact. A chat initiated by the contact must already exist before you can use this URL. For more information, see Send Response Messages via Webhook API.

To deactivate an active integration, select Stop under Actions.

Activate a Custom Webhook for Chatbot Service

If you saved the Custom Webhook integration without connections, activate it before associating it with a Chatbot Service automation.

The saved integration appears under the Integrations tab as a card. The card shows the alias, URL, integration ID, API details, and actions to delete, edit, or activate the integration.

To activate the integration:

1. Select Start ▶.
2. Confirm that the integration card changes to the active state.

After the Custom Webhook integration is active, configure the Chatbot automation that will use it. See the Chatbot section for configuration steps.

After you create the Chatbot and enable it in Live status, the integration card displays the active state and the Details icon.

Select the Automations icon to view the automation linked to the Custom Webhook integration.

The dialog displays:

• Campaign Id: Unique identifier of the automation.
• Campaign Name: Name of the automation.
• Integration Date: Date when the automation was created, linked to the integration, and enabled in Live status.

Select the API Details tab to view the endpoint URL, headers, parameters, and responses. Use the Try Out tab to send response events to chats initialized by a contact. A chat initiated by the contact must already exist before you can use this URL.

Remove a Custom Webhook linked to automations

You cannot pause or stop a Custom Webhook integration while it is linked to automations. If you try to pause it, the platform displays a dialog indicating that the requested action is invalid.

To remove a Custom Webhook integration linked to automations:

1. Disable the Live automations associated with the Custom Webhook integration.
2. Go to the Live automation associated with the Custom Webhook integration.
3. Select Report.
4. Select Pause.
5. In the confirmation dialog, select Confirm.

After you disable the associated automations:

1. Return to the Integrations tab from the References section.
2. Select Pause.
3. Optional: To delete the integration, select the Delete icon from the Actions buttons.

Send response messages via Webhook API

Use the Webhook API to send outbound messages, also known as MT (Mobile Terminated) messages, from your system to an end user through an existing Custom Webhook chat session.

This endpoint does not start new conversations. It injects events into existing chats, so it requires an active chat context. A chat can become active in different ways depending on the broadcast and business logic.

The Custom Webhook integration uses two endpoints:

• Client Webhook endpoint: The external endpoint you configure in the Custom Webhook integration. The platform sends inbound events generated by the contact, such as MO (Mobile Originated) messages, to this endpoint.
• Response Webhook endpoint: The endpoint generated by the platform for the integration. Your system sends outbound MT response messages to this endpoint to inject them into an existing chat session.

A common response flow works like this:

1. Your business sends an outbound SMS or WhatsApp message to the contact, such as a notification, broadcast message, or operational alert.
2. The contact replies to that message.
3. The platform receives the reply as an inbound message event, also known as an MO message.
4. The inbound message creates or activates a chat session associated with the contact and the communication flow.
5. The platform sends the inbound event in JSON format to the Client Webhook endpoint configured in the integration.
6. Your system receives and processes the inbound event data.
7. Your system sends a new outbound MT message to the Response Webhook endpoint associated with the integration, targeting the existing chat session.
8. The platform receives the request, routes the outbound message through the appropriate sender and channel configuration, and delivers it to the contact.

MT response messages are valid only when a chat already exists. If the contact has not initiated the conversation, there is no active chat context, and the MT request cannot be associated with a session.

Endpoint URL

Send MT messages with a POST request to this endpoint:

https://elastic.messangi.me/integrations/live-chat/{{ID_Integration}}/chats/{{chatIdentifier}}/events

Path parameters:

• {{ID_Integration}}: ID of the Custom Webhook integration.
• {{chatIdentifier}}: Contact number of the contact who will receive the message.

Required headers:

• Authorization: Valid Bearer token.
• Content-Type: application/json.

SMS POST message example

Use this JSON structure to send an outbound SMS message through the Webhook API:

{
  "type": "MESSAGE",
  "channel": {
    "type": "SMS",
    "route": "141518",
    "connection": "AWSexample121218"
  },
  "msg": "Thank you for attending. We look forward to seeing you again soon."
}

WhatsApp POST message example

If a WhatsApp user sends your application a message, either as a reply to one of your outbound message templates or by initiating the conversation, your application has a 24-hour customer service window to send messages without using a message template.

Messages sent within this 24-hour window are known as Session Messages. The following example sends a WhatsApp Session Message and can be used only while the 24-hour window is active.

{
  "type": "MESSAGE",
  "channel": {
    "type": "WHATSAPP",
    "sender": "584123149352"
  },
  "msg": "Thank you for attending. We look forward to seeing you again soon."
}

Test the endpoint URL

After you create and activate the Custom Webhook integration, test the endpoint URL from the Communications Platform. Testing lets you simulate an outbound message response and verify that your endpoint and routing configuration work before moving to production.

To test the endpoint URL:

1. Go to Preferences → Integrations.
2. Locate your Custom Webhook integration.
3. Select the Details icon on the integration card.

The platform opens the integration configuration window.

4. Select the API Details tab.
5. Open the Try Out sub-tab.

The platform displays the endpoint URL used to send response events to active chats.

6. Under Identify Chat By, select Contact.
7. In the Contact field, enter the contact number.
8. Select the internal connection identifier linked to the SMS or WhatsApp configuration defined in the Custom Webhook Connections section.
9. Choose the MESSAGE event type.
10. In the Message field, enter the message content to deliver to the contact.

As you complete these fields, the platform generates the corresponding cURL request on the right side of the screen.

Copy the generated cURL request and paste it into your terminal. The generated request includes the endpoint URL, required Bearer token authorization header, Content-Type: application/json header, and JSON request body that contains the message event.

Use the response to confirm that the message was injected into the active chat session and routed through the configured broadcast.