Skip to main content
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

1

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
2

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.
3

Handle the event payload

Webhook payloads include type, id, token, and event_data.
{
  "type": "message_recieved",
  "id": 123,
  "token": "WEBHOOK_VERIFICATION_TOKEN",
  "event_data": {
    "id": 9980041,
    "text": "What are your hours?",
    "phone": "15105553344",
    "date": "2026-04-16T14:22:00Z"
  }
}
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.

​
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.