Receive webhook events

Webhooks let Heymarket send event notifications to your server when messages, conversations, opt-in state, or call activity changes. Use webhooks for workflows that need to react without polling the REST API.

How delivery works

Heymarket sends an HTTPS POST request to your configured webhook URL. Your receiver should parse the JSON body, validate the token for the webhook configuration, persist what it needs, and return a 2xx response quickly. If processing may take more than a short moment, acknowledge the webhook first and move the work to a queue. Make processing idempotent with type plus a stable ID inside event_data when one is present, so repeated deliveries do not create duplicate work.

Steps

Create an HTTPS receiver

Create a public HTTPS endpoint that accepts POST requests with JSON bodies.

webhook receiver

from flask import Flask, request

app = Flask(__name__)

@app.route("/webhooks/heymarket", methods=["POST"])
def handle_heymarket_event():
    payload = request.get_json()
    if not payload:
        return "", 400

    if payload.get("token") != "WEBHOOK_VERIFICATION_TOKEN":
        return "", 401

    # Queue follow-up work before returning if processing will be slow.
    print(payload["type"], payload["id"])
    return "", 200

Configure the webhook URL

Add the HTTPS endpoint in the Heymarket app webhook settings. Store the webhook verification token from that configuration and compare it with the token value in every payload.

For app configuration steps, see the Heymarket Help Center article: Getting Started with Webhooks.

Webhook URLs are configured in the Heymarket app. The public REST API reference documents webhook payloads, but it does not provide a webhook-management endpoint.

Handle the event payload

Webhook payloads include type, id, token, and event_data.

{
  "type": "message_recieved",
  "id": "6f1d5b0c-2a4e-4c8f-9b3a-7d2e1f4a8c60",
  "token": "WEBHOOK_VERIFICATION_TOKEN",
  "event_data": {
    "id": 9980041,
    "text": "What are your hours?",
    "target": "15105553344",
    "phone": "14155550188",
    "date": "2026-04-16T14:22:00Z"
  }
}

The envelope id is a UUID generated for the event, not a webhook configuration ID. Every webhook configuration that receives the same event receives the same id, so pair it with type to deduplicate deliveries.The event_data shape depends on the event type. Message events send a message object, conversation events send a conversation object, and opt-in or opt-out events send an unsubscribe-state object.

Event types

Webhook type values include:

message_sent
message_recieved
chat_reassigned
chat_closed
chat_opened
chat_pending
chat_transferred
target_opt_out
target_opt_in
target_double_opt_in
target_double_opt_restricted
incoming_call

The current API spelling is message_recieved. Match that exact value when branching on inbound-message events.

Message event payload

message_sent and message_recieved events send a message object as event_data. For the full field list, see the webhook event reference. When you write a receiver for message events, plan for these behaviors:

Most fields are omitted when empty. Treat a missing key as an empty or zero value rather than requiring it.
user identifies the sending team member and is omitted on incoming messages. Use its presence to tell outbound from inbound.
super is the conversation ID. The full conversation is also embedded as conversation.
Group messages set targets with the individual phone numbers and sender with the sending number. On those events target is a single |-separated string.
status and raw_error apply to outbound messages. For group messages, per-target failures arrive in target_errors, keyed by target.
hidden marks a message whose content is withheld, so content fields can be empty even though the message exists.

The flagged field appears in the message schema but is not populated on webhook deliveries.

Example

An inbound SMS delivers a payload like this.

{
  "type": "message_recieved",
  "id": "6f1d5b0c-2a4e-4c8f-9b3a-7d2e1f4a8c60",
  "token": "WEBHOOK_VERIFICATION_TOKEN",
  "event_data": {
    "id": 9980041,
    "target": "15105553344",
    "text": "What are your hours?",
    "length": 20,
    "date": "2026-04-16T14:22:00Z",
    "updated": "2026-04-16T14:22:00Z",
    "super": 4417723,
    "team_id": 51204,
    "phone": "14155550188",
    "channel": "sms",
    "hidden": false,
    "conversation": {
      "id": 4417723,
      "inbox": 83125,
      "assigned": 6602,
      "target": "15105553344",
      "channel": "sms",
      "status": "active",
      "created": "2026-03-02T18:04:11Z",
      "updated": "2026-04-16T14:22:00Z",
      "unread_users": [6602],
      "tags": []
    }
  }
}

Security

Keep webhook URLs private.
Validate the token value before processing the event.
Do not expose webhook URLs in client-side code or public repositories.
Use separate webhook URLs for separate environments.
Log event type, webhook ID, and processing outcome for troubleshooting.

Webhooks concept

Understand where webhooks fit with REST API calls.

Messages reference

Send follow-up messages after webhook events.

Webhook event reference

Review the generated webhook payload schema.

Get Started

Core Concepts

Guides

How delivery works

Steps

Event types

Message event payload

Example

Security

Webhooks concept

Messages reference

Webhook event reference

​How delivery works

​Steps

​Event types

​Message event payload

​Example

​Security

​Related pages

Webhooks concept

Messages reference

Webhook event reference

How delivery works

Steps

Event types

Message event payload

Example

Security

Related pages