Webhooks

In this guide, we will look at how to register and consume webhooks to integrate your app with Protocol. With webhooks, your app can know when something happens in Protocol, such as someone sending a message or adding a contact.

Registering webhooks

To register a new webhook, you need to have a URL in your app that Protocol can call. You can configure a new webhook from the integration under Virtualpay » Integration.

Whenever something a status change happens to the transaction, the webhook will be triggered

Consuming webhooks

When your app receives a webhook request, check the transaction_id attribute to fully fetch the transaction update or use the endpoint provided in path

{
  "id": 30,
  "transaction_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "transaction_amount": "0.00",
  "transaction_e2e_id": "XXXXXXXX",
  "transaction_operation": "in or out",
  "transaction_reference": "generated_by_client",
  "extra": "generated_by_client",
  "date_created": "YYYY-mm-dd HH:mm:ss",
  "status": "paid",
  "path": "/api/v1/transaction/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
}

In the example above, a transaction has been updated and the status has changed to paid .
Status types can be:     pending   paid   partially_paid   denied   canceled   refund   in_process   in_analysis   expired

Security

To be sure that a webhook was indeed sent over protocol rather than a malicious actor, you can check the called header authorization Bearer {key}. This key is provided when registering a new webhook and each one has its own encrypted key.

It is essential to keep your webhook secret key safe, otherwise you can no longer be sure that a given webhook is authentic.