Webhook

Using Adisyo Webhook

With Adisyo Webhook, you can start listening to (subscribe) events, and when these events occur, you can have a URL you specify triggered (trigger) by Adisyo.

Basic Endpoint Creation

Your webhook endpoint should be an HTTP service that accepts POST requests.

1. Create a Simple Endpoint

const express = require('express');
const app = express();
 
// JSON body parsing
app.use(express.json());
 
// Webhook endpoint
app.post('/webhook', (req, res) => {
  console.log('Webhook received:', req.body);
  res.status(200).json({ success: true });
});
 
app.listen(3000, () => {
  console.log('Webhook server running: http://localhost:3000');
});

2. Expose Your Endpoint

Use ngrok for local development:

# ngrok installation
npm install -g ngrok
 
# Start your server
node webhook-server.js
 
# Start ngrok in another terminal
ngrok http 3000

ngrok will give you a URL like this:

https://abc123.ngrok.io

3. Configure in Adisyo Panel

  1. Go to Adisyo panel
  2. Go to App Store > Webhook section
  3. Click Create New Webhook button
  4. Enter the following information:
    • Company Name: Webhook Name (maximum 10 characters)
    • Service URL: https://abc123.ngrok.io/webhook
  5. Click Create Webhook button
  6. Copy the generated API Key
⚠️

Keep the API Key in a secure place. This key is critical for webhook security.

URL Verification

Adisyo verifies your webhook URL by sending a special request:

app.post('/webhook', (req, res) => {
  // URL verification - Adisyo sends "adisyo" string
  if (req.body === 'adisyo') {
    return res.status(200).send('adisyo');
  }
  
  // Normal webhook processing
  console.log('Webhook received:', req.body);
  res.status(200).json({ success: true });
});

URL verification is only done once when the webhook is created. You must respond to this request with "adisyo".

Endpoint Requirements

Your webhook endpoint must meet the following requirements:

RequirementDescription
HTTP MethodsMust accept POST requests, must reject GET requests
Response FormatSuccess: HTTP 200, Error: HTTP 4xx/5xx
Response TimeMaximum 5 seconds
SecurityUse HTTPS, verify signature, apply rate limiting

Example Endpoint Implementation

import express from 'express';
import { createHmac, timingSafeEqual } from 'crypto';
const app = express();
 
app.use(express.json());
 
const API_KEY = process.env.ADISYO_API_KEY;
 
// Signature verification function
function verifySignature(payload, signature, apiKey) {
  const webhookData = JSON.parse(payload);
  const message = `${webhookData.WebhookEventType}|${webhookData.EventTimeUtc}|${apiKey}`;
  const expectedSignature = createHmac('sha256', apiKey)
    .update(message)
    .digest('base64');
  
  return timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}
 
app.post('/webhook', (req, res) => {
  try {
    // URL verification
    if (req.body === 'adisyo') {
      return res.status(200).send('adisyo');
    }
    
    // Signature verification
    const signature = req.headers['x-adisyo-signature'];
    if (!verifySignature(JSON.stringify(req.body), signature, API_KEY)) {
      return res.status(401).json({ error: 'Invalid signature' });
    }
    
    // Process webhook
    console.log('Webhook received:', req.body);
    res.status(200).json({ success: true });
    
  } catch (error) {
    console.error('Webhook error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});
 
app.listen(3000);

Next Steps

To secure your webhook and process events:

Courier UsersSignature Verification