## Ticket Events & Webhooks

This page explains how to react to ticket movements (creation, status changes, new comments) and which real-time integrations Envia offers around tickets.

ℹ️
There is no dedicated outbound webhook for ticket status changes. Ticket movements are surfaced through in-app notifications, push, and WhatsApp for the account owner, and are consumed programmatically via polling. The only ticket-adjacent outbound webhook is the surcharge event, which fires for overweight tickets.

Recommended pattern: polling

To track a ticket's progress from your application, poll the ticket endpoints and compare ticket_status_id / updated_at between calls.

Step	Endpoint	Purpose
1	`GET /company/tickets?status_group=active`	Discover open tickets
2	`GET /company/tickets/{ticket_id}`	Read the current status of one ticket
3	`GET /company/tickets/comments/{ticket_id}`	Detect new replies in the thread

curl --request GET \
  --url 'https://queries.envia.com/company/tickets/987654' \
  --header 'Authorization: Bearer YOUR_API_TOKEN'

A change in ticket_status_id (see Ticket statuses) or a newer updated_at means the ticket moved.

Real-time notifications (dashboard)

When a ticket moves, Envia emits real-time notifications so the account sees the update instantly in the dashboard:

In-app notification — added to the company notification feed.
Push notification — sent to the user's registered devices.
WhatsApp — a templated message for key ticket events.

These channels target the Envia account/user, not an external server URL, so they are not something your backend subscribes to.

Surcharge webhook

The only outbound webhook connected to the ticket flow is the surcharge event. When an Overweight ticket (type 3) is processed, the related surcharge can be applied or refunded — and each fires a surcharge webhook.

Register it

Surcharge is a standard webhook type. Look up its id and subscribe your HTTPS endpoint. See the full Webhooks Guide for registration, signing, and retries.

# 1) Find the surcharge webhook type id
curl --request GET \
  --url https://queries.envia.com/webhook-types \
  --header 'Authorization: Bearer YOUR_API_TOKEN'

# 2) Register your endpoint (surcharge = type_id 5)
curl --request POST \
  --url https://queries.envia.com/webhooks \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "type_id": 5,
    "url": "https://your-app.com/webhooks/envia",
    "active": 1
  }'

Payload — charge applied

{
  "type": "surcharge",
  "created_at": "2026-07-08T14:23:05.000Z",
  "data": {
    "surcharge_id": 12345,
    "shipment_id": 98765,
    "tracking_number": "1Z999AA10123456784",
    "carrier_name": "UPS",
    "surcharge_data": {
      "surcharge_type": "Overweight",
      "reason": "Package exceeds declared weight limit",
      "amount": 85.50,
      "currency": "MXN",
      "transaction_type": "surcharge"
    }
  }
}

Payload — charge refunded

An overweight ticket resolved in the customer's favor triggers a refund with the same structure but transaction_type: "refund":

{
  "type": "surcharge",
  "created_at": "2026-07-08T09:10:00.000Z",
  "data": {
    "surcharge_id": 12350,
    "shipment_id": 98765,
    "tracking_number": "1Z999AA10123456784",
    "carrier_name": "UPS",
    "surcharge_data": {
      "surcharge_type": "Overweight",
      "reason": "",
      "amount": 85.50,
      "currency": "MXN",
      "transaction_type": "refund"
    }
  }
}

Field reference

Field	Description
`surcharge_type`	Category of the charge (e.g. `Overweight`, `Return to Origin`, `Po Box`).
`transaction_type`	`"surcharge"` = charge applied · `"refund"` = charge reversed.
`amount`	Always positive — use `transaction_type` to determine direction.
`currency`	ISO 4217 code (e.g. `MXN`, `USD`, `COP`).
`shipment_id` / `tracking_number`	The shipment the charge belongs to — match it back to your overweight ticket.

Delivery headers

Every delivery includes signing and dedup headers. Always verify X-Webhook-Signature before processing.

Header	Description
`X-Webhook-Event`	Event type (e.g. `surcharge`).
`X-Webhook-Version`	API version date (e.g. `2025-09-01`).
`X-Webhook-Id`	Unique delivery ID for deduplication.
`X-Webhook-Timestamp`	Unix timestamp (ms).
`X-Webhook-Signature`	`v1=HMAC-SHA256(ts + "." + event + "." + body_json, secret)`.

⚠️
Respond 2xx within 5 seconds and process asynchronously. Deduplicate using X-Webhook-Id. See the Webhooks Guide for the production checklist.

Correlating a surcharge event with a ticket

The webhook payload carries shipment_id (and tracking_number), not ticket_id. To tie an incoming surcharge back to its overweight ticket:

Receive the surcharge webhook.
Call GET /company/tickets?tracking_number={tracking_number}&type=3 to find the Overweight ticket for that shipment.
Read its ticket_status_id to confirm the resolution.