​
Get started

To start receiving webhook events in your app, create and register a webhook endpoint by following the steps below:

  1. Create a webhook endpoint handler to receive event data POST requests.
  2. Register your endpoint within Fungies Dashboard.
  3. Secure your webhook endpoint.

You can register and create one endpoint to handle several different event types at once, or set up individual endpoints for specific events.

​
1. Create a webhook endpoint handler

Set up an HTTP or HTTPS endpoint function that can accept webhook requests with a POST method. If you’re still developing your endpoint function on your local machine, it can use HTTP. After it’s publicly accessible, your webhook endpoint function must use HTTPS.

Set up your endpoint function so that it:

  • Handles POST requests with a JSON payload consisting of an event object.
  • Quickly returns a successful status code (2xx) prior to any complex logic that could cause a timeout.
// This example uses Express to receive webhooks
import express from "express";
const app = express();

app.post('/webhook', express.json({type: 'application/json'}), (request, response) => {
  const event = request.body;

  // Handle the event
  switch (event.type) {
    case 'payment_success':
      // handlePaymentSuccess(event.data);
      break;
    case 'payment_refund':
      // handlePaymentRefund(event.data);
      break;
    // ... handle other event types
    default:
      console.log(`Unhandled event type ${event.type}`);
  }

  response.json({success: true});
});

app.listen(8081, () => console.log('Running on port 8081'));

​
2. Register your endpoint within Fungies Dashboard

To register your endpoint, go to the Fungies Dashboard and navigate to the Developers -> Webhooks section.

Click the Create a webhook button and fill in the form with the following information:

  • URL: The URL of your endpoint. If you are using ngrok, use the https://... url you copied in the previous step.
  • Secret: A secret key that will be used to sign the webhook events. You can use any string here, but it should be kept secret and used to verify the signature of the events.
  • Choose the events you want to receive. You can select one or more events to receive at this endpoint.

Click the Save button to register your endpoint.

From now on, your endpoint will receive events from Fungies and you can start processing them.

​
3. Secure the webhook endpoint

We highly recommend you secure your endpoint by ensuring your handler verifies that all webhook request are generated by Fungies. This can be done by verifying the signature of the event using the secret key you provided when registering the endpoint.

The x-fngs-signature header included in each signed event contains the signature and is prefixed by sha256_.

x-fngs-signature: sha256_6808ed5be1262b60818359fa586145810d0793e8a677f1326520d3844e21b640

Fungies generates signatures using a hash-based message authentication code HMAC with SHA-256.

In order to verify the signature, you should use the secret key you provided when registering the endpoint and the raw body of the request.

​
Standalone function example

// This example shows standalone function to verify webhook event signature
import crypto from "crypto";

const verifyWebhookEventSignature = (payload: Buffer, signature: string, secret: string) => {
    const hmac = crypto.createHmac("sha256", secret);
    return `sha256_${hmac.update(payload.toString()).digest("hex")}` === signature;
};

​
Express middleware example

// This example uses Express to receive webhooks
import express, { Response, Request } from "express";
import crypto from "crypto";

const WEBHOOK_SECRET = "<YOURE_SECRET_HERE>";

const app = express();

const verifyWebhookEventSignature = (request: Request, response: Response, buf: Buffer, encoding: string) => {
    const signature = request.header('x-fngs-signature');
    const hmac = crypto.createHmac("sha256", WEBHOOK_SECRET);
    const calcSignature = `sha256_${hmac.update(buf.toString(encoding)).digest("hex")}`;
    request["signature_match"] = (calcSignature === signature);
};

app.post('/webhook', express.json({
  type: 'application/json',
  verify: verifyWebhookEventSignature
}), (request, response) => {
  if(!request["signature_match"]) {
    return response.status(403).send('signature mismatch');
  }

  // Do something with the event
  // ...
});

app.listen(8081, () => console.log('Running on port 8081'));