Webhooks

Webhooks let you subscribe to events and receive real-time notifications when those events occur in your Corpay account. Use webhooks when you need Corpay to notify your system of an event instead of polling for updates.

How do Webhooks work?

Sample Payload

 
  {
    "EventType": "PaymentAccepted",
    "CreatedDate": "2023-03-30T11:04:59.846784-04:00",
    "ClientCode": "{clientCode}",
    "Id": "{clientCode}-P5MBEP",
    "MessageId": "d2fa6482-c4c3-4a7a-9957-73ca1931143d"
  }

When to use?

• Use REST APIs when you need to query data on demand.
• Use Webhooks when you need to be notified immediately when an event occurs to avoid constant polling.

Webhooks Security - Signature verification

To ensure secure communication, each webhook request includes a digital Corpay-Signature in the Headers. You can use this signature to authenticate the payload and prevent man-in-the-middle (MITM) attacks.

• The header includes a Unix timestamp with an encrypted key in SHA1 cryptographic hash format, created using HMAC.
• You can verify the authenticity of the notification by decrypting this header with HMAC to confirm if it matches the key (shared during implementation).

 
  {
  	"EventType": "PaymentProcessed",
  	"CreatedDate": "2023-03-30T12:01:20.9526609-04:00",
  	"ClientCode": "220829",
  	"Id": "{clientCode}-P5MBEP",
  	"MessageId": "4c3319ea-9986-4140-bcd4-c397a17bc669"
  }

 
  Corpay-Signature: t=1680192080,v1=8dd6434ab8d1efe8c04f2854f856eac5780d7dfc
  Content-Type: application/json