FedaPay can send webhooks that notify to your application each time an event occurs on your account. This is especially useful for events such as contested or successful transactions. This mechanism is also useful for services which are not directly responsible for creating an API request, but which nevertheless need to know the answer to that request.

You can define Webhooks URLs which will be used to inform you each time an event occurs on your account. When an event such as approved transaction occurs, FedaPay creates anEvent object.

This Event object contains all the relevant information about what happened, including the event type and the data associated with that event. FedaPay then sends the Event object via an HTTP POST request to all endpoint URLs that you have defined in the Webhook settings of your account. You can ask FedaPay to send one event to many webhook endpoints.

Configure the settings of your webhooks

Webhooks are configured in the Webhooks section on the dashboard.

Click Create a new webhook or New webhook to display a form where you can add a new URL to receive webhooks. You can enter any URL as destination for events. However, it must be a dedicated page on your server configured to receive notifications on the web. You can choose to be notified for all types of events, or only specific ones.

Once your webhook is created, you can view the details, edit or even delete it. Click on a webhook to make any change you want.

Webhook signatures verification

FedaPay signs the Webhook events which are sent to your endpoint (Url by which FedaPay can join your application). We do this by including a signature in the header of each X-FEDAPAY-SIGNATURE event. This allows you to verify that the events were sent by FedaPay and not by a third party. You can verify signatures using our official libraries or manually using your own solution.

Before you can verify the signatures, you must retrieve the secret key of your endpoint from the Webhook settings on your dashboard. Select the webhook for which you wish to obtain the secret key, then click on the Copy key button.

Each secret key is unique on the endpoint to which it corresponds. If you use the same endpoint for the test and active API keys, note that the secret key is different for each one. After this configuration, FedaPay starts signing each Webhook sent to the endpoint.

Verification of signatures using our official libraries

We recommend to use one of our official libraries to verify the signatures. You perform the verification by providing the content of the event, the X-FEDAPAY-SIGNATURE header, and the endpoint's secret key. If the verification fails, FedaPay returns an error.

// You can find your endpoint's secret key in your webhook settings
$endpoint_secret = 'wh_sandbox.......';

$payload = @file_get_contents('php://input');
$sig_header = $_SERVER['HTTP_X_FEDAPAY_SIGNATURE'];
$event = null;

try {
    $event = \FedaPay\Webhook::constructEvent(
        $payload, $sig_header, $endpoint_secret
    );
} catch(\UnexpectedValueException $e) {
    // Invalid payload

    http_response_code(400);
    exit();
} catch(\FedaPay\Error\SignatureVerification $e) {
    // Invalid signature

    http_response_code(400);
    exit();
}

// Handle the event
switch ($event->name) {
    case 'transaction.created':
        // Transaction created
        break;
    case 'transaction.approved':
        // Transaction approved
        break;
    case 'transaction.canceled':
        // Transaction canceled
        break;
    default:
        http_response_code(400);
        exit();
}

http_response_code(200);

const { Webhook } = require('fedapay')

// You can find your endpoint's secret key in your webhook settings
const endpointSecret = 'wh_sandbox...';

// This example uses Express to receive webhooks
const app = require('express')();

// Use body-parser to retrieve the raw body as a buffer
const bodyParser = require('body-parser');

// Match the raw body to content type application/json
app.post('/webhook', bodyParser.raw({type: 'application/json'}), (request, response) => {
  const sig = request.headers['x-fedapay-signature'];

  let event;

  try {
    event = Webhook.constructEvent(request.body, sig, endpointSecret);
  } catch (err) {
    response.status(400).send(`Webhook Error: ${err.message}`);
  }

  // Handle the event
  switch (event.name) {
    case 'transaction.created':
      // Transaction created
      break;
    case 'transaction.approved'':
      // Transaction approved
      break;
    case 'transaction.canceled'':
      // Transaction canceled
      break;
    default:
      console.log(`Unhandled event type ${event.type}`);
  }

  // Return a response to acknowledge receipt of the event
  response.json({received: true});
});

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