Technical Resources

Webhook Events

Receive real-time notifications when events happen in Fareplay. Instead of polling the API, configure webhook endpoints and we will send HTTP POST requests to your server the moment an order is placed, a cart moves, or a payment is processed.

How Webhooks Work

1
An event occurs
A golfer places an order, a cart changes status, or a payment is processed.
2
Fareplay sends a POST request
We deliver a JSON payload to your configured webhook URL with full event details.
3
Your server processes the event
Verify the signature, handle the event, and respond with a 200 status code.

Available Events

Subscribe to any combination of events. Each event type delivers a specific payload relevant to the action that occurred.

Orders

`order.created`	Triggered when a golfer places a new order from the course.
`order.accepted`	Triggered when cart staff accepts and begins preparing the order.
`order.completed`	Triggered when the order has been delivered to the golfer.
`order.cancelled`	Triggered when an order is cancelled by staff or the golfer.

Carts

`cart.status_changed`	Triggered when a cart goes online or offline for the day.
`cart.location_updated`	Triggered when a cart GPS position changes beyond the movement threshold.

Payments

`payment.completed`	Triggered when a payment is successfully processed via Stripe.
`payment.refunded`	Triggered when a full or partial refund is issued for an order.

Webhook Delivery Headers

Every webhook delivery includes these headers so you can identify and verify the request.

POST /webhooks/fareplay HTTP/1.1
Host: your-server.com
Content-Type: application/json
X-Fareplay-Signature: sha256=a1b2c3d4e5f6...
X-Fareplay-Event: order.created
X-Fareplay-Delivery: evt_9xKmL3nPqR
User-Agent: Fareplay-Webhooks/1.0

Example Payload

Here is an example payload for the order.created event. All payloads follow the same top-level structure with event metadata and a data object containing the event-specific information.

{
  "id": "evt_9xKmL3nPqR",
  "type": "order.created",
  "created_at": "2026-03-17T14:32:00Z",
  "data": {
    "order_id": "ord_8x7kLm2nP",
    "status": "pending",
    "hole_number": 7,
    "cart_id": "cart_3fR9v",
    "items": [
      {
        "name": "Draft IPA",
        "quantity": 2,
        "unit_price": 8.00
      },
      {
        "name": "Turkey Wrap",
        "quantity": 1,
        "unit_price": 12.50
      }
    ],
    "total": 35.78,
    "customer": {
      "name": "Jordan M.",
      "phone_last_four": "4821"
    }
  }
}

Security & Signature Verification

Every webhook request includes an X-Fareplay-Signature header containing an HMAC-SHA256 hash of the request body. Always verify this signature using your webhook secret to confirm the request was sent by Fareplay and has not been tampered with.

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler:
app.post('/webhooks/fareplay', (req, res) => {
  const signature = req.headers['x-fareplay-signature'];
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    process.env.FAREPLAY_WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process the event
  const event = req.body;
  switch (event.type) {
    case 'order.created':
      handleNewOrder(event.data);
      break;
    case 'order.completed':
      handleOrderComplete(event.data);
      break;
    // ... handle other events
  }

  res.status(200).json({ received: true });
});

Always verify signatures. Never process webhook payloads without validating the signature first. Your webhook secret is available in the admin dashboard under Settings > Webhooks.

Retry Policy

If your endpoint does not respond with a 2xx status code within 30 seconds, Fareplay will retry the delivery using exponential backoff.

Attempt	Delay	Notes
1st retry	1 minute	Immediate retry after initial failure
2nd retry	10 minutes	Exponential backoff applied
3rd retry	1 hour	Final attempt before marking as failed

After 3 failed retries, the delivery is marked as failed. You can view and manually retry failed deliveries from the admin dashboard. If your endpoint fails consistently, webhooks will be automatically disabled and you will be notified via email.

Setup & Configuration

Configure webhook endpoints directly from your Fareplay admin dashboard. You can create multiple endpoints and subscribe each one to different event types.

1.Log in to your Fareplay Admin Dashboard
2.Navigate to Settings > Webhooks
3.Click Add Endpoint and enter your server URL
4.Select which event types you want to subscribe to
5.Copy the generated webhook secret and store it securely on your server
6.Use the Send Test Event button to verify your endpoint

Ready to integrate?

Sign up for Fareplay and start receiving real-time event notifications. Set up your first webhook endpoint in minutes from the admin dashboard.

Get Started