Sweet Spot API

Command Palette

Search for a command to run...

Webhooks

Webhooks allow your application to receive real-time notifications when events occur in the Sweet Spot API. Instead of polling for changes, webhooks push event data to your endpoint as events happen.

Overview

When you register a webhook, you provide an HTTPS endpoint URL and select which events you want to receive. When those events occur, we send an HTTP POST request to your endpoint with the event data.

Getting Started

  1. Create a Webhook: Register a webhook endpoint and select which events to subscribe to
  2. Store Your Secret: Save the webhook secret securely—you'll need it to verify incoming requests
  3. Receive Events: When subscribed events occur, we'll POST event data to your endpoint
  4. Verify & Process: Always verify the webhook signature before processing events

Tip: Use the test webhook endpoint to send test events to your endpoint and verify your integration before going live.

Available Events

Subscribe to specific event types to receive notifications. Events are organized by resource type. There are 58 event types available across all categories.

Checkout Lifecycle Events

Track a checkout from creation through fulfillment and delivery.

Event TypeDescriptionWhen Triggered
checkout.createdNew checkout was createdCustomer initiates checkout flow
checkout.updatedCheckout was modifiedAny checkout field update
checkout.completedLease is now activeFulfillment complete, lease active (LeaseActive state)
checkout.cancelledCheckout was cancelledAdmin or customer cancellation
checkout.expiredCheckout timed outCheckout exceeded expiration window
checkout.deposit_paidDeposit payment confirmedDeposit payment succeeds
checkout.documents_signedLease documents signedDocument signing completed
checkout.order_confirmedReady to ship productDocuments signed and deposit captured (FulfillmentPending state)
checkout.fulfilledOrder was fulfilledFulfillment completed
checkout.shippedTracking number addedShipment tracking attached
checkout.deliveredPackage deliveredCarrier confirms delivery
checkout.tracking_updatedTracking status changedAny tracking status update
checkout.fulfillment_exceptionDelivery issue occurredReturn or delivery failure
checkout.tracking_staleTracking stalledNo updates for extended period
checkout.deposit_resetDeposit reset by adminAdmin resets failed ACH deposit

Key Events for Fulfillment

  • checkout.order_confirmed — This is your signal to start fulfillment. The customer has signed documents and the deposit has been captured. Ship the product now.
  • checkout.completed — The entire checkout process is done. Fulfillment is complete, the customer has the product, and the lease is active.

Subscription & Recurring Payment Events

Monitor subscription status and recurring payment outcomes.

Event TypeDescriptionWhen Triggered
checkout.subscription_activeSubscription activatedRecurring billing goes active
checkout.subscription_past_duePayment past dueSubscription payment fails
checkout.subscription_cancelledSubscription cancelledSubscription terminated
checkout.payment_failedRecurring payment failedInvoice payment fails
checkout.payment_recoveredPayment recoveredPast due payment succeeds

ACH & Deposit Payment Events

Track ACH bank transfer status for deposit payments.

Event TypeDescriptionWhen Triggered
checkout.payment_processingACH payment in-flightBank transfer initiated
checkout.deposit_failedACH payment failedBank transfer rejected/returned
checkout.payment_action_requiredAction neededCustomer action required
checkout.payment_expiredPre-auth expiredPayment pre-authorization expired

Customer Events

Event TypeDescriptionWhen Triggered
customer.createdNew customer createdCustomer record created
customer.updatedCustomer updatedCustomer info modified
customer.credit_check_completedCredit check doneCredit verification finished

Product Events

Event TypeDescriptionWhen Triggered
product.createdProduct createdNew product added
product.updatedProduct updatedProduct info modified
product.deletedProduct deletedProduct removed

Lease & Lease Term Events

Event TypeDescriptionWhen Triggered
lease.startedLease beganLease term started
lease.endedLease endedLease term completed
lease_term.createdLease term createdNew term added
lease_term.deletedLease term deletedTerm removed

Product Fee Events

Event TypeDescriptionWhen Triggered
product_fee.createdFee createdNew fee added
product_fee.updatedFee updatedFee modified
product_fee.deletedFee deletedFee removed

Payment Events

Event TypeDescriptionWhen Triggered
payment.receivedPayment receivedAny payment recorded

Fulfillment Events

Event TypeDescriptionWhen Triggered
fulfillment.createdFulfillment createdFulfillment record created
fulfillment.updatedFulfillment updatedFulfillment info modified

Organization Events

Event TypeDescriptionWhen Triggered
organization.createdOrganization createdNew org added
organization.updatedOrganization updatedOrg info modified

User & API Token Events

Event TypeDescriptionWhen Triggered
user.createdUser createdNew user added
user.updatedUser updatedUser info modified
user.deletedUser deletedUser removed
api_token.createdAPI token createdNew API token generated
api_token.revokedAPI token revokedAPI token invalidated

Webhook Management Events

Event TypeDescriptionWhen Triggered
webhook.createdWebhook registeredNew webhook endpoint added
webhook.updatedWebhook updatedWebhook config modified
webhook.deletedWebhook deletedWebhook endpoint removed

Invitation Events

Event TypeDescriptionWhen Triggered
invitation.createdInvitation sentUser invited to org
invitation.acceptedInvitation acceptedUser accepted invite

Webhook Payload

When an event occurs, your endpoint receives an HTTP POST request with a JSON payload containing the event type, unique event ID, timestamp, and the relevant resource data.

Request Headers

Every webhook request includes these headers:

HeaderDescription
X-Webhook-SignatureHMAC-SHA256 signature (format: sha256=hex_signature)
X-Webhook-TimestampUnix timestamp when the request was signed
X-Webhook-Event-TypeThe event type (e.g., checkout.created)
X-Webhook-Event-IDUnique identifier for this event (use for deduplication)

Example Payload

JSON
{
  "id": "evt_1234567890",
  "type": "checkout.order_confirmed",
  "data": {
    "id": "chk_123456",
    "state": "LeaseActive",
    "productVariantId": "pvar_123456",
    "customerId": "cust_123456",
    "createdAt": "2024-01-15T10:30:00Z"
  },
  "createdAt": "2024-01-15T10:30:00Z"
}

Delivery & Retries

We make every effort to deliver webhooks reliably. If your endpoint doesn't respond with a 2xx status code, we'll automatically retry with exponential backoff.

Retry Schedule

AttemptDelay
1st attemptImmediate
2nd attempt60 seconds
3rd attempt5 minutes
4th attempt30 minutes
5th attempt2 hours
Final attempt24 hours

Retryable Errors

  • 5xx server errors
  • 429 rate limit errors
  • Connection timeouts

Non-Retryable Errors

  • 4xx client errors (except 429)
  • Invalid endpoint URL
  • SSL/TLS errors

Replaying Events: If you need to replay a failed webhook event, you can use the webhook audit endpoints to retrieve delivery logs and replay specific events.

Security

All webhook requests are signed so you can verify they came from Sweet Spot and haven't been tampered with.

Security Features

  • HTTPS Required: Webhook URLs must use HTTPS (localhost and private IPs are blocked)
  • HMAC Signing: Every request is signed with SHA-256 using your webhook secret
  • Timestamp Validation: Timestamps allow you to reject stale requests and prevent replay attacks
  • Full Audit Trail: All webhook deliveries are logged for debugging and compliance

Signature Format

The signature is computed as:

signature = hex(HMAC-SHA256(secret, timestamp + "." + payload))

To verify a webhook:

  1. Extract the signature from X-Webhook-Signature (remove sha256= prefix)
  2. Get the timestamp from X-Webhook-Timestamp
  3. Reconstruct the signed payload: timestamp + "." + request_body
  4. Compute HMAC-SHA256 with your webhook secret
  5. Compare using constant-time comparison
  6. Optionally reject requests older than 5 minutes

Example: Verify Signature (Node.js)

JavaScript
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret, timestamp) {
  // Reconstruct the signed payload
  const signedPayload = `${timestamp}.${payload}`;

  // Compute the expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  // Extract the signature from the header (format: sha256=hex_signature)
  const receivedSignature = signature.replace('sha256=', '');

  // Compare signatures using constant-time comparison
  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature),
    Buffer.from(receivedSignature)
  );
}

// Example usage in Express.js
app.post('/webhooks/sweetspot', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];
  const eventType = req.headers['x-webhook-event-type'];
  const eventId = req.headers['x-webhook-event-id'];

  const webhookSecret = process.env.WEBHOOK_SECRET;

  if (!verifyWebhookSignature(req.body, signature, webhookSecret, timestamp)) {
    return res.status(401).send('Invalid signature');
  }

  // Check timestamp to prevent replay attacks (recommended)
  const currentTime = Math.floor(Date.now() / 1000);
  const requestTime = parseInt(timestamp);
  if (Math.abs(currentTime - requestTime) > 300) { // 5 minutes tolerance
    return res.status(401).send('Request timestamp too old');
  }

  const event = JSON.parse(req.body);

  // Process the webhook event
  console.log('Received event:', eventType, eventId);

  res.status(200).send('OK');
});

Important: Always verify webhook signatures before processing events. Never trust webhook requests without verification. Store your webhook secret securely and never expose it in client-side code.

Best Practices

1. Always Verify Signatures

Never process webhook events without verifying the HMAC signature. This ensures the request is authentic and hasn't been tampered with.

2. Respond Quickly (Within 5 Seconds)

Return a 2xx status code as quickly as possible. If you need to do heavy processing, acknowledge the webhook first, then process asynchronously using a job queue.

3. Handle Duplicates Idempotently

Webhooks may be delivered multiple times during retries. Use the X-Webhook-Event-IDheader to deduplicate and ensure your processing is idempotent.

4. Use HTTPS Endpoints

Webhook URLs must use HTTPS to ensure payload encryption in transit. HTTP endpoints and localhost/private IPs are not supported.

5. Test Before Going Live

Use the test webhook endpoint to send test events and verify your implementation handles events correctly before subscribing to production events.

6. Monitor Delivery Health

Use the webhook audit endpoints to monitor delivery success rates and investigate failures. Set up alerts for repeated delivery failures.

Webhooks Guide | Sweet Spot API Documentation