Documentation

Webhook Setup

Configure webhooks to receive real-time notifications about events in your Inkress account.

What are Webhooks?

Webhooks allow Inkress to send real-time notifications to your server when important events occur in your account. Instead of constantly polling our API for updates, webhooks push data to your application as soon as events happen.

Common use cases: Send order confirmation emails, update inventory after payments, trigger fulfillment workflows, sync transaction data to accounting systems, and notify customers of payout status.

Creating a Webhook Endpoint

1. Set Up Your Server Endpoint

Create an HTTP endpoint on your server that can receive POST requests from Inkress. Here's a basic example:

app/routes/webhooks.inkress.tsxtypescript
1// Remix action example
2export async function action({ request }: ActionFunctionArgs) {
3  if (request.method !== 'POST') {
4    return json({ error: 'Method not allowed' }, { status: 405 });
5  }
6
7  // Parse webhook payload
8  const payload = await request.json();
9  
10  // Verify webhook signature (see Security section)
11  const signature = request.headers.get('X-Inkress-Signature');
12  if (!verifyWebhookSignature(payload, signature)) {
13    return json({ error: 'Invalid signature' }, { status: 401 });
14  }
15
16  // Process the webhook event
17  const { event_type, data } = payload;
18  
19  switch (event_type) {
20    case 'payment.success':
21      await handlePaymentSuccess(data);
22      break;
23    case 'order.created':
24      await handleOrderCreated(data);
25      break;
26    // ... handle other events
27  }
28
29  // Return 200 to acknowledge receipt
30  return json({ received: true });
31}

2. Register Your Webhook URL

Add your webhook endpoint URL in the Inkress dashboard or via the API:

Via Dashboard

  1. Navigate to Settings → Webhooks
  2. Click "Add Endpoint"
  3. Enter your webhook URL (e.g., https://yoursite.com/webhooks/inkress)
  4. Select which events you want to receive
  5. Save your webhook configuration

Via API

1const response = await admin.webhookUrls.create({
2  url: 'https://yoursite.com/webhooks/inkress',
3  events: [
4    'payment.success',
5    'payment.failed',
6    'order.created',
7    'payout.completed'
8  ],
9  status: 1  // active
10});

3. Test Your Webhook

Use the dashboard to send test events to your endpoint:

  1. Go to Settings → Webhooks
  2. Select your webhook endpoint
  3. Click "Send Test Event"
  4. Choose an event type to simulate
  5. Verify your server receives and processes the test payload

Best Practices

1. Return 200 Quickly

Your endpoint should return a 200 OK response as quickly as possible. Process webhook data asynchronously to avoid timeouts.

1export async function action({ request }: ActionFunctionArgs) {
2  const payload = await request.json();
3  
4  // Queue for async processing
5  await jobQueue.add('process-webhook', payload);
6  
7  // Return immediately
8  return json({ received: true });
9}

2. Handle Idempotency

Webhooks may be sent multiple times. Use the event ID to ensure you only process each event once.

1const { id, event_type, data } = payload;
2
3// Check if we've already processed this event
4const existing = await db.webhookEvent.findUnique({ where: { id } });
5if (existing) {
6  return json({ received: true }); // Already processed
7}
8
9// Store the event ID
10await db.webhookEvent.create({ data: { id, processed_at: new Date() } });
11
12// Process the event
13await processEvent(event_type, data);

3. Use HTTPS

Always use HTTPS endpoints in production to ensure webhook data is encrypted in transit. Inkress will reject non-HTTPS URLs for production webhooks.

4. Monitor Webhook Deliveries

Check the webhook delivery logs in your dashboard to monitor success rates and debug failures.

5. Implement Retry Logic

If your endpoint is temporarily down, Inkress will retry failed webhook deliveries with exponential backoff. However, you should also implement your own fallback mechanisms.

Retry Policy

If your endpoint returns a non-2xx status code or times out, Inkress will automatically retry the webhook delivery:

1

Immediate retry after 1 minute

2

Second retry after 5 minutes

3

Third retry after 30 minutes

4

Fourth retry after 2 hours

5

Final retry after 6 hours

After all retry attempts fail, the webhook delivery is marked as failed. You can manually retry failed deliveries from the dashboard.

Troubleshooting

Webhooks Not Receiving

  • Verify your endpoint URL is publicly accessible
  • Check that you're listening for POST requests
  • Ensure your firewall allows incoming requests from Inkress
  • Verify HTTPS certificate is valid (not self-signed)

Timeouts

  • Endpoint must respond within 30 seconds
  • Move long-running processes to background jobs
  • Return 200 immediately and process asynchronously

Invalid Signatures

  • Verify you're using the correct webhook signing secret
  • Check that you're computing the signature correctly
  • Ensure you're using the raw request body (not parsed JSON)
← SDKsWebhook Events →