Webhooks

Zazpay webhooks allow you to receive automatic real-time notifications about important events that occur in the payment system. This functionality is particularly useful for keeping point-of-sale systems synchronized with transaction status without the need for constant API queries.

Webhooks are delivered as HTTP requests to a URL configured by the merchant. Each notification includes contextual data about the event and headers to help you verify authenticity.

How to configure a webhook

Step 1: Access the Webhooks Dashboard

1. Navigate to hub.zazpay.mx/webhooks
2. Ensure you are logged in with an admin or developer user account

Step 2: View Current Webhooks

• You will see a list of all available webhooks
• Each webhook displays:
  • Brief description of the event
  • Current status (enabled/disabled)
  • Configuration details

Step 3: Configure a Webhook

1. Click on the webhook you want to configure

2. You will be taken to the configuration page where you can set up:

   Basic Settings:

   • Enable/Disable Switch: Toggle the webhook on or off
   • Webhook URL: Enter the endpoint URL where notifications will be sent
   • Request Method: Choose one of: GET, HEAD, POST, PUT, PATCH, DELETE

   Advanced Settings:

   • Custom Headers: Add any additional HTTP headers required by your endpoint
   • Body Structure: Define the fields included in the request body
   • Content Type: Select one of: text/plain, application/json, application/xml, application/x-www-form-urlencoded

Step 4: Save Configuration

• Review your settings
• Click save to activate the webhook configuration
• The webhook will immediately start sending notifications to your specified endpoint

Security and verification

To verify that webhook requests originate from zazpay, implement one of the following:

• Bearer token: Configure a static token and validate it from the Authorization: Bearer <token> header.

If both are configured, verify both. Reject requests that fail verification with HTTP 401.

Events and payload variables

Different events expose different payload variables. Select the event to see which variables are available to include in the payload.

Transaction Created

The event is emitted when a transaction is created.

Available variables:

Variable	Type	Description
folio	string	Transaction folio
status	string	Current status at creation time
clientEmail	string	Client email
clientPhoneNumber	string	Client phone number
amount	number	Transaction amount
ticket	string	Optional reference/ticket
storeName	string	Store name
storeId	string	External store identifier
createdAt	string	Creation timestamp (ISO 8601)
approvedAt	string	Approval timestamp if available (ISO 8601)
salesmanReference	string	Salesman reference/identifier
salesmanName	string	Salesman name

Transaction Status Change

The event is emitted when a transaction status changes (e.g., IN_PROGRESS → APPROVED/REJECTED/CANCELED).

Available variables:

Variable	Type	Description
folio	string	Transaction folio
status	string	New status
clientEmail	string	Client email
clientPhoneNumber	string	Client phone number
amount	number	Transaction amount
ticket	string	Optional reference/ticket
storeName	string	Store name
storeId	string	External store identifier
createdAt	string	Creation timestamp (ISO 8601)
approvedAt	string	Approval timestamp if available (ISO 8601)
salesmanReference	string	Salesman reference/identifier
salesmanName	string	Salesman name

Client Affiliated

The event is emitted when a client is created/affiliated in your company.

Available variables:

Variable	Type	Description
name	string	Client given name
firstSurname	string	Client paternal surname
secondSurname	string	Client maternal surname
fullName	string	Full name
email	string	Client email
phoneNumber	string	Client phone number
affiliationDate	string	Affiliation timestamp (ISO 8601)
zipCode	string	ZIP/postal code

Client Updated

The event is emitted when client data is updated.

Available variables:

Variable	Type	Description
name	string	Client given name
firstSurname	string	Client paternal surname
secondSurname	string	Client maternal surname
fullName	string	Full name
email	string	Client email
phoneNumber	string	Client phone number
affiliationDate	string	Original affiliation timestamp (ISO 8601)
zipCode	string	ZIP/postal code

HTTP methods and content types

• Allowed methods: GET, HEAD, POST, PUT, PATCH, DELETE
• For GET and HEAD, no request body is sent. Use headers and query string if needed.
• For POST, PUT, PATCH, and DELETE, the request body is sent using the configured content type.
• Supported content types: text/plain, application/json, application/xml, application/x-www-form-urlencoded

Example payload (Transaction Status Change)

{
  "folio": "12345678",
  "status": "APPROVED",
  "clientEmail": "customer@example.com",
  "clientPhoneNumber": "9999999999",
  "amount": 1500.0,
  "ticket": "TCK-12345",
  "storeName": "Main Store",
  "storeId": "ext_store_456",
  "createdAt": "2024-01-15T10:30:00Z",
  "approvedAt": "2024-01-15T10:32:15Z",
  "salesmanReference": "9999999999",
  "salesmanName": "John Doe"
}

Notes:

• For GET/HEAD deliveries, the same fields can be provided as query parameters, depending on your configuration.
• Store the idempotency key header we include to deduplicate retries.