Skip to main content
Webhooks let Heymarket push event notifications to your server the moment something happens — a new inbound message, an outbound message delivery update, or a change to a conversation. Instead of polling the API repeatedly, your server receives a POST request with a JSON payload as soon as the event occurs. This makes webhooks the right tool for real-time workflows like auto-responses, CRM syncs, and escalation routing.

​
How webhooks work

When an event occurs in Heymarket, the platform sends an HTTP POST request to the URL you configure. The request body is a JSON object containing event details, using the same message and conversation structure returned by the REST API. Your server must respond with HTTP 200 to acknowledge receipt. If Heymarket does not receive a 200, it will retry the delivery.

​
Setup steps

1

Set up a public HTTPS endpoint

Your webhook receiver must be accessible over the public internet via HTTPS. Create an endpoint on your server that accepts POST requests and reads the JSON body. During local development you can use a tunneling tool like ngrok to expose a local port.
example receiver (Python/Flask)
from flask import Flask, request

app = Flask(__name__)

@app.route("/webhook/heymarket", methods=["POST"])
def handle_event():
    payload = request.get_json()
    # Process the event here
    print(payload)
    return "", 200
2

Configure the webhook URL in Heymarket

Log in to Heymarket and navigate to Settings. Enter your public HTTPS endpoint URL in the webhook configuration field. Save the setting to activate delivery.
For full configuration instructions, see the Heymarket Help Center: Getting Started with Webhooks.
3

Receive POST requests with event payloads

Once configured, Heymarket sends a POST request to your endpoint each time a subscribed event occurs. The payload is a JSON object with event details. Log and inspect the first few events to understand the structure before building your processing logic.Example inbound message payload:
{
  "event": "message_received",
  "message": {
    "id": 9980041,
    "text": "What are your hours?",
    "direction": "inbound",
    "date": "2026-04-16T14:22:00Z",
    "phone_number": "15105553344"
  },
  "chat": {
    "id": 123456,
    "inbox_id": 42
  }
}
4

Respond with HTTP 200

Return an HTTP 200 status as quickly as possible — before doing any heavy processing. If your handler takes too long or returns a non-200 status, Heymarket will retry the delivery. Offload time-consuming work to a background queue after acknowledging the request.
acknowledgement
HTTP/1.1 200 OK

​
Payload structure

Webhook payloads follow the same object structure as REST API responses. Each payload includes:
  • event — the event type (e.g., message_received, message_sent, chat_updated)
  • message — the message object with id, text, direction, date, and sender/recipient details
  • chat — the conversation object with id, inbox_id, and other conversation metadata
Inspect live payloads during setup to confirm the exact field names for the events relevant to your integration.

​
Security

Heymarket recommends keeping your webhook URL private. Do not publish it in client-side code or public repositories. If your endpoint is compromised, update the URL in Heymarket settings immediately. Consider validating that incoming requests originate from Heymarket by checking the source IP or adding a secret token to your endpoint URL path that only your server and Heymarket know.
For full configuration steps and additional security guidance, see the Heymarket Help Center article: Getting Started with Webhooks.

​
Common use cases

  • Route inbound SMS replies — parse the message text and forward to the correct team or system based on keywords or contact data.
  • Sync CRM records — update a contact record in your CRM whenever a message is sent or received, keeping communication history in one place.
  • Trigger auto-responses — detect specific keywords in inbound messages and immediately send a reply via POST /v1/message/send.
  • Escalate conversations — monitor for unanswered messages and alert a supervisor or open a support ticket after a defined time threshold.
Use webhook events as triggers in your automation workflows rather than polling GET /v1/chats on a schedule. Event-driven processing is faster, uses fewer API calls, and reacts to activity in real time.