> ## Documentation Index
> Fetch the complete documentation index at: https://developers.heymarket.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Receive webhook events

> Configure a webhook receiver for Heymarket events, validate the payload token, and acknowledge deliveries quickly.

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

<Steps>
  <Step title="Create an HTTPS receiver">
    Create a public HTTPS endpoint that accepts `POST` requests with JSON bodies.

    ```python webhook receiver theme={null}
    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
    ```
  </Step>

  <Step title="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.

    <Note>
      For app configuration steps, see the Heymarket Help Center article: [Getting Started with Webhooks](https://help.heymarket.com/hc/en-us/articles/4416494130701-Getting-Started-with-Webhooks).
    </Note>

    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.
  </Step>

  <Step title="Handle the event payload">
    Webhook payloads include `type`, `id`, `token`, and `event_data`.

    ```json theme={null}
    {
      "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.
  </Step>
</Steps>

## 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`

<Note>
  The current API spelling is `message_recieved`. Match that exact value when branching on inbound-message events.
</Note>

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

## Related pages

<CardGroup cols={2}>
  <Card title="Webhooks concept" icon="webhook" href="/concepts/webhooks">
    Understand where webhooks fit with REST API calls.
  </Card>

  <Card title="Messages reference" icon="code" href="/api-reference/messages/send">
    Send follow-up messages after webhook events.
  </Card>

  <Card title="Webhook event reference" icon="webhook" href="/api-reference/webhooks">
    Review the generated webhook payload schema.
  </Card>
</CardGroup>