# Webhooks

## Overview

**Webhooks** allow menta tech to notify your platform in real time whenever a relevant event occurs in the resale ecosystem. Instead of polling for changes, your system receives HTTP POST requests with structured event data as they happen.

Webhooks are essential for:

* Keeping your platform in sync with resale activity
* Triggering downstream processes (ticket delivery, reporting, CRM updates)
* Tracking marketplace activity (listings, sales, payouts)
* Enabling real-time user notifications

## General Payload Structure

Every webhook sent by menta tech follows a consistent envelope format:

```json
{
  "message": {
    "family": "<event_family>",
    "action": "<event_action>",
    "type": "<event_subtype>",
    "data": { ... }
  }
}
```

{% table highlight-first=true %}
| Field | Description |
| :--- | :--- |
| `family` | Groups related events (e.g., `listing`, `ticket`, `event`, `notifyMe`, `payouts`). |
| `action` | The specific event that occurred (e.g., `listing.created`, `ticket.updated`). |
| `type` | Provides additional context about the event variant (e.g., `SINGLE`, `MULTI`, `USER_TRANSFER`). Not present in all events. |
| `data` | The event-specific payload containing the relevant information. |
{% /table %}

## Events Summary

{% table highlight-first=true %}
| Family | Action | Description |
| :--- | :--- | :--- |
| **listing** | `listing.created` | A new listing has been published in the secondary market. |
| **listing** | `listing.updated` | An existing listing has been modified (e.g., price change). |
| **listing** | `listing.deleted` | A listing has been removed from the secondary market. |
| **ticket** | `ticket.updated` | A resale has been completed and ticket ownership has changed. |
| **event** | `event.unlock` | Tickets have been unlocked for an event. |
| **notifyMe** | `notifyMe.created.updated` | A "Notify Me" subscription has been created or updated. |
| **payouts** | `payouts.delivered` | Payouts for an event/show have been sent to sellers. |
{% /table %}

---

## Important Notes on Identifiers

{% callout type="warning" %}
Most identifiers in webhook payloads — such as `ticketId`, `eventId`, `showId`, and the `id` field in `ticket.updated` — originate from **your platform**. They correspond to the IDs you assigned when creating or syncing these resources with menta tech.

The following identifiers are generated by **menta tech**:
* `listingId` — Unique identifier for a marketplace listing.
* `groupId` — Groups tickets within the same listing operation.
* `resaleId` — Unique identifier for a completed resale transaction.
* `id` (in `notifyMe` events) — Unique identifier for a "Notify Me" subscription.
{% /callout %}

---

## Event Details

{% conditionaltabs id="tabs-webhooks-families" %}
{% tab label="Listing" %}
## Listing Events

Listing events notify your platform about changes in the resale marketplace inventory. These events are triggered whenever a user creates, updates, or removes a ticket listing.

The `type` field in listing events indicates whether the listing involves a single ticket (`SINGLE`) or multiple tickets (`MULTI`).

### listing.created

Triggered when a user publishes a new listing in the secondary market.

```json
{
  "message": {
    "family": "listing",
    "action": "listing.created",
    "type": "MULTI",
    "data": {
      "ticketId": "5102",
      "sellerEmail": "maria.garcia@example.com",
      "listingId": "70cde790d4e17236e08587g2",
      "listingPrice": 1500,
      "listingFinalPrice": 1725,
      "listingPayout": {
        "type": "LOCAL_FIAT_AUTOMATIC",
        "data": {
          "paymentMethod": "emoneyout-mxn_012",
          "userForm": {
            "beneficiary_name": "Maria",
            "beneficiary_lastname": "Garcia",
            "bank_account": "014027000012345678",
            "bank_account_type": "checking"
          }
        }
      },
      "groupId": "70cde790d4e17236e08587ec"
    }
  }
}
```

### listing.updated

Triggered when a user modifies an existing listing (e.g., price change).

```json
{
  "message": {
    "family": "listing",
    "action": "listing.updated",
    "type": "SINGLE",
    "data": {
      "ticketId": "T3FB2E891AA4208",
      "listingId": "70cedef51c3fcd8f74d0e4e1",
      "listingPrice": 14,
      "listingFinalPrice": 16.1,
      "listingPayout": {
        "type": "LOCAL_FIAT_AUTOMATIC",
        "data": {
          "paymentMethod": "dlocal-emoneyout-mxn_138",
          "userForm": {
            "beneficiary_name": "Jorge",
            "beneficiary_lastname": "Ramirez",
            "bank_account": "072180001098765432"
          }
        }
      },
      "groupId": "70cedef51c3fcd8f74d0e4d8",
      "sellerEmail": "jorge.ramirez@example.com"
    }
  }
}
```

### listing.deleted

Triggered when a listing is removed from the secondary market, either by the user or by the system.

```json
{
  "message": {
    "family": "listing",
    "action": "listing.deleted",
    "type": "MULTI",
    "data": {
      "ticketId": "5102",
      "sellerEmail": "maria.becerra@example.com",
      "listingId": "70cde6551b66d4098c5523dc",
      "listingPrice": 1500,
      "listingFinalPrice": 1725,
      "listingPayout": {
        "type": "LOCAL_FIAT_AUTOMATIC",
        "data": {
          "paymentMethod": "emoneyout-mxn_012",
          "userForm": {
            "beneficiary_name": "Maria",
            "beneficiary_lastname": "Becerra",
            "bank_account": "014027000012345678",
            "bank_account_type": "checking"
          }
        }
      },
      "groupId": "70cde6551b66d4098c5523c6"
    }
  }
}
```

### Listing Payload Fields

| Field | Description | ID Source |
| :--- | :--- | :--- |
| `ticketId` | The ticket identifier. | Your platform |
| `sellerEmail` | Email or phone number of the seller. | — |
| `listingId` | Unique identifier of the listing. | menta tech |
| `listingPrice` | The price set by the seller (before fees). | — |
| `listingFinalPrice` | The final buyer-facing price (including fees). | — |
| `listingPayout` | Payout configuration and method details for the seller. | — |
| `groupId` | Identifier grouping multiple tickets in a single listing operation. | menta tech |

{% /tab %}
{% tab label="Ticket" %}
## Ticket Events

### ticket.updated

Triggered when a resale transaction is completed and ticket ownership changes from the seller to the buyer. This is the key event for initiating ticket delivery on your platform.

```json
{
  "message": {
    "family": "ticket",
    "action": "ticket.updated",
    "type": "USER_TRANSFER",
    "data": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "newOwnerEmail": "carlos.lopez@example.com",
      "oldOwnerEmail": "ana.martinez@example.com",
      "reversal": false,
      "metadata": {
        "nominal": {
          "fullName": "Carlos Lopez",
          "identificationType": "DNI",
          "identification": "30567890",
          "externalEmail": "carlos.lopez@example.com",
          "email": "carlos.lopez@example.com"
        },
        "payer": {
          "fullName": "Carlos Lopez",
          "identificationType": "DNI",
          "identification": "30567890",
          "externalEmail": "carlos.lopez@example.com",
          "email": "carlos.lopez@example.com"
        },
        "seller": {
          "fullName": "Ana Martinez",
          "identification": "28901234",
          "identificationType": "DNI"
        },
        "order": {
          "resaleId": "70ceeed4d4e17236e085e472",
          "grossResalePaidAmount": 103816.25,
          "grossResalePaidAmountWithoutBuyerFee": 90275,
          "sellerFee": 0.15,
          "sellerFeeAmount": 11775,
          "buyerFee": 0.15,
          "buyerFeeAmount": 13541.25
        }
      }
    }
  }
}
```

{% callout type="info" %}
This is the most critical webhook for ticket fulfillment. When you receive a `ticket.updated`, your platform should immediately initiate the ticket delivery process to the new owner.
{% /callout %}

{% callout type="warning" title="Transaction Reversals" %}
When `reversal` is `true`, the transaction is being reversed — the ticket must be returned to the previous owner. In this case, `metadata.nominal` contains the previous owner's information (if available). Your platform should undo the original transfer accordingly.
{% /callout %}

### ticket.updated Payload Fields

| Field | Description | ID Source |
| :--- | :--- | :--- |
| `id` | The ticket identifier. | Your platform |
| `newOwnerEmail` | Email of the buyer (new ticket owner). | — |
| `oldOwnerEmail` | Email of the seller (previous ticket owner). | — |
| `reversal` | `true` if the transaction is being reversed (e.g., chargeback, refund). When `true`, `metadata.nominal` contains the previous owner's data if available. Defaults to `false`. | — |
| `metadata.nominal` | Identity details of the person the ticket is nominally assigned to. | — |
| `metadata.payer` | Identity details of the person who paid for the ticket. | — |
| `metadata.seller` | Identity details of the seller. | — |
| `metadata.order.resaleId` | Unique identifier for the resale transaction. | menta tech |
| `metadata.order.grossResalePaidAmount` | Total amount paid by the buyer (including all fees). | — |
| `metadata.order.grossResalePaidAmountWithoutBuyerFee` | Amount paid excluding the buyer fee. | — |
| `metadata.order.sellerFee` | Seller fee as a decimal (e.g., `0.15` = 15%). | — |
| `metadata.order.sellerFeeAmount` | Absolute seller fee amount deducted from the sale. | — |
| `metadata.order.buyerFee` | Buyer fee as a decimal (e.g., `0.15` = 15%). | — |
| `metadata.order.buyerFeeAmount` | Absolute buyer fee amount added to the sale price. | — |

{% /tab %}
{% tab label="Event" %}
## Event Events

### event.unlock

Triggered when tickets are unlocked for an event. This typically occurs when the event organizer enables or modifies resale activity.

{% callout type="warning" %}
After an `event.unlock`, existing listings may remain active in the marketplace, but no new listings can be created. Your platform should take this into account when displaying resale options to users.
{% /callout %}

```json
{
  "message": {
    "family": "event",
    "action": "event.unlock",
    "data": {
      "eventId": "8544",
      "showId": "8544",
      "excludedEmailTicketIds": []
    }
  }
}
```

### event.unlock Payload Fields

| Field | Description | ID Source |
| :--- | :--- | :--- |
| `eventId` | The event identifier. | Your platform |
| `showId` | The show identifier. | Your platform |
| `excludedEmailTicketIds` | List of ticket IDs excluded from the unlock operation. When empty, all tickets are included. | Your platform |

{% /tab %}
{% tab label="Notify Me" %}
## Notify Me Events

### notifyMe.created.updated

Triggered when a user creates or updates a "Notify Me" subscription. These subscriptions allow users to express interest in tickets for a specific event and get notified when matching tickets become available within their price preferences.

```json
{
  "message": {
    "family": "notifyMe",
    "action": "notifyMe.created.updated",
    "data": {
      "id": "70cedf0685b7a892dc5c9418",
      "showId": "7322",
      "eventId": "7322",
      "userEmail": "pedro.sanchez@example.com",
      "status": "ACTIVE",
      "ticketQuantity": 1,
      "ticketOptionSelections": [
        {
          "ticketOptionId": "36790",
          "priceLimit": 13799
        },
        {
          "ticketOptionId": "36821",
          "priceLimit": 17250
        },
        {
          "ticketOptionId": "36822",
          "priceLimit": 20700
        },
        {
          "ticketOptionId": "37489",
          "priceLimit": 110400
        },
        {
          "ticketOptionId": "38029",
          "priceLimit": 4140
        }
      ],
      "createdAt": "2026-03-20T22:49:41.338Z",
      "updatedAt": "2026-03-20T23:45:57.869Z"
    }
  }
}
```

### notifyMe.created.updated Payload Fields

| Field | Description | ID Source |
| :--- | :--- | :--- |
| `id` | Unique identifier of the subscription. | menta tech |
| `showId` | The show identifier. | Your platform |
| `eventId` | The event identifier. | Your platform |
| `userEmail` | Email of the subscribed user. | — |
| `status` | Current status of the subscription (e.g., `ACTIVE`). | — |
| `ticketQuantity` | Number of tickets the user is looking for. | — |
| `ticketOptionSelections` | Array of ticket categories with maximum price preferences. | — |
| `ticketOptionSelections[].ticketOptionId` | The ticket option/category identifier. | Your platform |
| `ticketOptionSelections[].priceLimit` | Maximum price the user is willing to pay for that category. | — |
| `createdAt` | ISO 8601 timestamp when the subscription was created. | — |
| `updatedAt` | ISO 8601 timestamp of the last update. | — |

{% /tab %}
{% tab label="Payouts" %}
## Payout Events

### payouts.delivered

Triggered when payouts for a specific event or show have been processed and sent to the sellers.

```json
{
  "message": {
    "family": "payouts",
    "action": "payouts.delivered",
    "data": {
      "showId": "239616",
      "eventId": "12746"
    }
  }
}
```

### payouts.delivered Payload Fields

| Field | Description | ID Source |
| :--- | :--- | :--- |
| `showId` | The show identifier for which payouts were processed. | Your platform |
| `eventId` | The event identifier for which payouts were processed. | Your platform |

{% /tab %}
{% /conditionaltabs %}