Subscriptions (Webhooks)

Subscribe to real-time webhook events for third-party app lifecycle management. Receive notifications about installations, uninstallations, and installation requests with HMAC authentication for security.

Overview

The Marketplace Subscriptions API enables your integration to receive real-time notifications about important events in the app lifecycle. Configure webhook endpoints to receive event notifications when merchants install or uninstall your app, or when installation requests are created or cancelled.

Key Features

  • Real-Time Notifications - Instant event delivery as changes occur
  • HMAC Authentication - Cryptographic signatures verify webhook authenticity
  • Comprehensive Events - Coverage for all installation lifecycle stages
  • Automatic Retries - Failed deliveries are retried with exponential backoff
  • Event History - Track and replay missed events

Authentication

HMAC (Hash-based Message Authentication Code)

To verify that the payloads your webhooks receive actually come from us, we require that you implement HMAC authentication schema.

HMAC constructs an information-rich header that contains information about the sender, while providing security to ensure that the request has not been forged or tampered with in transit.

Verifying Webhook Signatures

Each webhook request includes an HMAC signature in the headers. Verify signatures before processing:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const computedSignature = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(computedSignature)
  );
}

// In your webhook handler
app.post('/webhooks/marketplace', (req, res) => {
  const signature = req.headers['x-shift4-signature'];
  const payload = JSON.stringify(req.body);

  if (!verifyWebhookSignature(payload, signature, YOUR_WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook
  res.status(200).send('OK');
});

Always verify HMAC signatures before processing webhook payloads to ensure authenticity and prevent tampering.

Webhook Events

Third-Party App Uninstalled

Triggered when your app is removed from a location.

Event Name: marketplace.Location.deleted

When Triggered:

  • Merchant manually uninstalls your app from their location
  • System automatically removes installation due to policy violation
  • Integration is deleted from the Marketplace

Payload:

{
  "event": {
    "name": "marketplace.Location.deleted",
    "component": "marketplace",
    "resource": "Location",
    "action": "deleted",
    "version": "v1",
    "subscriptionId": 1,
    "dispatchedAt": "2019-10-15T17:00:00.000Z"
  },
  "payload": {
    "locationId": 1
  }
}

Required Response: 2xx status code

Use Cases:

  • Revoke access tokens for the location
  • Clean up merchant data (according to your data retention policy)
  • Disable integration features for the location
  • Send internal notifications about the uninstallation
  • Update billing or usage tracking

Installation Requested

Triggered when a merchant initiates installation of your app.

Event Name: marketplace.InstallationRequest.created

When Triggered:

  • Merchant clicks "Install" in the Shift4 Marketplace
  • Merchant submits the installation request form
  • Installation is initiated through the Lighthouse Token Flow

Payload:

{
  "event": {
    "name": "marketplace.InstallationRequest.created",
    "component": "marketplace",
    "resource": "InstallationRequest",
    "action": "created",
    "version": "v1",
    "subscriptionId": 1,
    "dispatchedAt": "2019-10-15T17:00:00.000Z"
  },
  "payload": {
    "locationId": 1,
    "guid": "07a3a97e-6154-4e18-97a0-4b59cdd79007"
  }
}

Required Response: 2xx status code

Use Cases:

  • Begin the onboarding process for the merchant
  • Retrieve full installation details using the guid
  • Update installation state to IN_PROGRESS
  • Send welcome email to merchant
  • Prepare merchant account in your system

Next Steps:

  1. Call GET /marketplace/v2/locations/{locationId}/requests/installations/{guid} to retrieve full details
  2. Update state to IN_PROGRESS via PATCH endpoint
  3. Begin merchant onboarding workflow
  4. Update to FULFILLED when complete

Installation Request Cancelled

Triggered when a pending installation is abandoned or cancelled.

Event Name: marketplace.InstallationRequest.cancelled

When Triggered:

  • Merchant explicitly cancels the installation
  • Installation request times out without completion
  • System cancels due to policy or validation failure

Payload:

{
  "event": {
    "name": "marketplace.InstallationRequest.cancelled",
    "component": "marketplace",
    "resource": "InstallationRequest",
    "action": "cancelled",
    "version": "v1",
    "subscriptionId": 1,
    "dispatchedAt": "2019-10-15T17:00:00.000Z"
  },
  "payload": {
    "locationId": 1,
    "guid": "07a3a97e-6154-4e18-97a0-4b59cdd79007"
  }
}

Required Response: 2xx status code

Use Cases:

  • Clean up in-progress onboarding data
  • Mark installation request as cancelled in your system
  • Stop any pending onboarding workflows
  • Update internal metrics and tracking
  • Free up any reserved resources

Installation Validation Requested

This event is triggered when an installation for a third-party app has been requested and needs additional validation.

Event Name: marketplace.InstallationValidation.created

When Triggered:

  • System requires additional verification before completing installation
  • Shift4 requests confirmation of integration prerequisites
  • Custom validation rules are triggered

Payload:

{
  "event": {
    "name": "marketplace.InstallationValidation.created",
    "component": "marketplace",
    "resource": "InstallationValidation",
    "action": "created",
    "version": "v1",
    "subscriptionId": 1,
    "dispatchedAt": "2019-10-15T17:00:00.000Z"
  },
  "payload": {
    "installationRequest": { }
  }
}

Payload matches the one provided during app installation.

Required Response: 200 or 204 status code

Use Cases:

  • Validate installation prerequisites
  • Verify merchant account setup is complete
  • Confirm integration readiness
  • Check API connectivity
  • Validate configuration settings

Best Practices

Webhook Security

  • Name
    Always Verify Signatures
    Description

    Never process webhook payloads without verifying HMAC signatures. This prevents unauthorized requests and tampering.

  • Name
    Validate Timestamps
    Description

    Check the dispatchTimestamp and reject events older than a few minutes to prevent replay attacks.

  • Name
    Use HTTPS
    Description

    Configure webhook endpoints with HTTPS only. Never use HTTP in production.

  • Name
    Rate Limiting
    Description

    Implement rate limiting on webhook endpoints to prevent abuse.

Event Processing

  • Name
    Process Asynchronously
    Description

    Return a 2xx status code immediately, then process webhooks asynchronously in background jobs.

  • Name
    Implement Idempotency
    Description

    Use the subscriptionId and dispatchTimestamp as idempotency keys to handle duplicate deliveries.

  • Name
    Log All Events
    Description

    Maintain comprehensive logs of all webhook events for debugging and audit purposes.

  • Name
    Retry Failed Operations
    Description

    If internal processing fails, implement retry logic with exponential backoff.

Error Handling

  • Name
    Return 2xx Even on Failure
    Description

    Always return 2xx status codes to acknowledge receipt, even if internal processing fails.

  • Name
    Dead Letter Queues
    Description

    Implement dead letter queues for events that repeatedly fail processing.

  • Name
    Monitor Failures
    Description

    Set up monitoring and alerting for webhook processing failures.

  • Name
    Alert on Critical Events
    Description

    Create alerts for critical events like installation failures or high error rates.

Operational Excellence

  • Name
    Monitor Latency
    Description

    Track webhook processing latency and set up alerts for slow processing.

  • Name
    Document Workflows
    Description

    Maintain clear documentation of webhook processing workflows for your team.

  • Name
    Audit Logs
    Description

    Keep audit logs of all installation events for compliance and support.

  • Name
    Test Thoroughly
    Description

    Test webhook handlers with valid/invalid signatures, duplicate events, and timeout scenarios.

Event Workflows

Complete Installation Flow

1. marketplace.InstallationRequest.created
   ↓ Receive webhook
   ↓ Verify HMAC signature
   ↓ Return 200 OK immediately
   ↓ Queue for async processing
   ↓ Retrieve installation details via API
   ↓ Update state to IN_PROGRESS
   ↓ Begin merchant onboarding

2. marketplace.InstallationValidation.created (if required)
   ↓ Receive webhook
   ↓ Validate prerequisites
   ↓ Return validation response

3. Complete onboarding
   ↓ Update state to FULFILLED
   ↓ Enable integration features

Uninstallation Flow

1. marketplace.Location.deleted
   ↓ Receive webhook
   ↓ Verify HMAC signature
   ↓ Return 200 OK immediately
   ↓ Queue for async processing
   ↓ Revoke access tokens
   ↓ Clean up merchant data
   ↓ Disable integration
   ↓ Update billing/usage

Was this page helpful?