Skip to main content

Webhooks Overview

Webhooks allow you to receive real-time notifications about events that happen in your OrcaRail account, such as when a payment succeeds or fails.

What are Webhooks?​

Webhooks are HTTP callbacks that OrcaRail sends to your server when specific events occur. Instead of polling the API to check for updates, webhooks push event data to your application in real-time.

How Webhooks Work​

  1. An event occurs in OrcaRail (e.g., a payment succeeds)
  2. OrcaRail sends an HTTP POST request to your webhook endpoint
  3. Your server responds with 200 OK to acknowledge receipt
  4. Your application processes the event

Setting Up Webhooks​

1. Create a Webhook Endpoint​

Create an HTTP endpoint in your application that can receive POST requests:

// Express.js example
app.post('/webhooks/orcarail', express.json(), (req, res) => {
  const event = req.body

  // Process the event
  handleWebhookEvent(event)

  // Always return 200 OK immediately
  res.status(200).json({ received: true })
})

2. Configure Your Webhook URL​

Configure your webhook endpoint URL when creating or updating an API key. The webhook URL should be:

  • Publicly accessible - OrcaRail needs to reach it from the internet
  • HTTPS - For security (required in production)
  • Fast - Respond with 200 OK within 10 seconds (timeout is 10 seconds)

See Webhook Configuration for detailed instructions on setting up webhooks.

3. Verify Webhook Signatures​

Always verify webhook signatures to ensure requests are actually from OrcaRail. See Webhook Signatures for details.

Webhook Events​

OrcaRail sends webhook events for various payment-related activities:

EventDescription
payment_intent.completedA Payment Intent has succeeded and payment has been processed
payment_intent.processingA Payment Intent is being processed on the blockchain
payment_intent.canceledA Payment Intent was canceled
payment_intent.requires_payment_methodA Payment Intent requires a payment method

See Webhook Events for detailed information about each event type.

Webhook Payload​

All webhook events follow this structure:

{
  "type": "payment_intent.completed",
  "data": {
    "object": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "amount": "100.00",
      "currency": "usd",
      "status": "completed",
      "metadata": {
        "order_id": "12345"
      }
    }
  }
}

Handling Webhooks​

Idempotency​

Webhooks may be sent multiple times for the same event. Always make your webhook handlers idempotent:

const processedEvents = new Set()

app.post('/webhooks/orcarail', express.json(), async (req, res) => {
  const event = req.body
  const eventId = `${event.type}_${event.data.object.id}`

  // Check if we've already processed this event
  if (processedEvents.has(eventId)) {
    return res.status(200).json({ received: true })
  }

  // Process the event
  await handleWebhookEvent(event)

  // Mark as processed
  processedEvents.add(eventId)

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

Respond Quickly​

Always respond with 200 OK within 10 seconds (the webhook timeout), then process the event asynchronously:

app.post('/webhooks/orcarail', express.json(), (req, res) => {
  const event = req.body

  // Respond immediately
  res.status(200).json({ received: true })

  // Process asynchronously
  processEventAsync(event).catch((error) => {
    console.error('Error processing webhook:', error)
  })
})

Error Handling​

If your endpoint returns a non-200 status code, OrcaRail will retry the webhook. Implement proper error handling:

app.post('/webhooks/orcarail', express.json(), async (req, res) => {
  try {
    const event = req.body

    // Verify signature
    verifyWebhookSignature(req)

    // Process event
    await handleWebhookEvent(event)

    res.status(200).json({ received: true })
  } catch (error) {
    console.error('Webhook error:', error)

    // Return 500 to trigger retry, or 200 if you don't want retries
    res.status(500).json({ error: 'Internal server error' })
  }
})

Testing Webhooks​

Using ngrok​

For local development, use ngrok to expose your local server:

ngrok http 3000

Then configure your webhook URL to https://your-ngrok-url.ngrok.io/webhooks/orcarail.

Testing with cURL​

You can test your webhook endpoint manually:

curl -X POST https://your-webhook-url.com/webhooks/orcarail \
  -H "Content-Type: application/json" \
  -H "x-webhook-signature: your-signature" \
  -d '{
    "type": "payment_intent.completed",
    "data": {
      "object": {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "amount": "100.00",
        "currency": "usd",
        "status": "succeeded"
      }
    }
  }'

Next Steps​