POS Webhooks

Real-time notifications for POS events via webhooks. Subscribe to events like ticket updates to keep your system synchronized with the POS.

Overview

POS webhooks (subscriptions) provide real-time notifications when specific events occur in the POS system. Instead of polling for changes, your application receives HTTP POST requests containing event data.

Benefits:

• Real-time Updates - Receive notifications within seconds of events
• Reduced API Calls - No need to poll for changes
• Efficient Synchronization - Keep systems in sync automatically
• Event-Driven Architecture - Build responsive integrations

Authentication

To verify that webhook payloads are genuinely from Shift4 and haven't been tampered with, you must implement HMAC authentication.

HMAC Signature Verification

HMAC (Hash-based Message Authentication Code) constructs an information-rich header that ensures the request:

• Actually comes from Shift4
• Has not been forged
• Has not been tampered with in transit

For detailed information on implementing HMAC authentication for webhooks, see the Overview Subscriptions documentation.

Quick Reference

Each webhook request includes HMAC headers:

• x-signature - The HMAC signature to verify
• x-timestamp - Unix timestamp of the request
• x-access-key - Your client ID

Verification steps:

1. Extract the request body and headers
2. Construct the signature string using method, path, body, and timestamp
3. Generate HMAC-SHA256 signature using your secret key
4. Compare generated signature with x-signature header
5. Reject request if signatures don't match

Available Subscriptions

Batch Ticket Updated

Notification when POS tickets are created or updated.

Event: pos.BatchTicket.updated

Availability: SkyTab POS only

Learn more →

Batch Ticket Updated

Receives notifications whenever tracked ticket fields are created or changed in the POS. Notifications are delivered near real-time, with up to a 3-minute delay.

Availability

Note: This subscription is currently available only for SkyTab POS. All other POS systems are not yet supported.

Tracked Fields

The following fields and objects trigger notifications when changed:

Ticket Fields

TicketItem Fields

TicketItemModifier Fields

TicketPayments Fields

Webhook Payload

{
  "event": {
    "name": "pos.BatchTicket.updated",
    "component": "pos",
    "resource": "BatchTicket",
    "action": "updated",
    "version": "v2",
    "subscriptionId": 51,
    "dispatchedAt": "2023-05-08T11:01:41.592Z"
  },
  "payload": {
    "tickets": [
      {
        "locationId": 2,
        "posRef": "3ba13095-93c2-48cc-87d3-e5a8cc21115f"
      },
      {
        "locationId": 2,
        "posRef": "677f9395-32bf-40cc-81fc-c43d59d7f289"
      },
      {
        "locationId": 1,
        "posRef": "7840c2dc-4d8f-47ad-97dd-f5fe54942920"
      }
    ]
  }
}

Processing Webhooks

When you receive a webhook:

1. Verify Signature - Always verify the HMAC signature before processing
2. Extract Ticket References - Get the array of affected tickets
3. Fetch Full Data - Use the Ticket Lookup API to get full ticket details:

curl -X POST https://conecto-api.shift4payments.com/pos/v2/lookup/tickets \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "filter": {
      "refs": [
        {
          "locationId": 2,
          "posRef": "3ba13095-93c2-48cc-87d3-e5a8cc21115f"
        }
      ]
    }
  }'

4. Update Your System - Process the ticket data and update your system
5. Return 200 OK - Acknowledge receipt within 30 seconds

Webhook Delivery

Timing:

• Near real-time delivery (up to 3-minute delay)
• Multiple tickets may be batched in a single webhook

Retries:

• Failed deliveries are retried with exponential backoff
• Return 200 OK within 30 seconds to avoid retries
• After multiple failures, subscription may be disabled

Best Practices:

• Process webhooks asynchronously (queue for background processing)
• Return 200 OK immediately, process later
• Implement idempotency (handle duplicate deliveries)
• Log all webhook receipts for debugging

Webhook Response

Your webhook endpoint must:

1. Verify HMAC Signature - Reject requests with invalid signatures
2. Return 200 OK - Within 30 seconds
3. Process Asynchronously - Don't block the webhook response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "received": true
}

Best Practices