Better, faster integration of business events using Webhooks
Webhooks
Many of the events related to payments are asynchronous by nature (a bank confirms a payment, a transfer is reversed, etc.). Therefore they may not be available to you, the API consumer, when a payment is made. Although the client can always check the state of each entity by calling the appropriate API endpoint, Devengo implements an easier way to provide the client with almost real-time notifications: webhooks.
These user-defined HTTPS callbacks will receive a JSON payload each time an event on Devengo's systems is produced. You can then use these notifications to execute actions in your backend systems.
Event Type list
This is the list of event types that will be send to any active webhook:
Event | Description |
---|---|
outgoing_payment.created | Occurs whenever an outgoing payment is created. |
outgoing_payment.validating | Occurs whenever an outgoing payment is being validated. |
outgoing_payment.blocked | Occurs whenever an outgoing payment has not passed the validation process. |
outgoing_payment.delayed | Occurs whenever an outgoing payment cannot be processed immediately. |
outgoing_payment.pending | Occurs whenever an outgoing payment is pending. |
outgoing_payment.denied | Occurs whenever an outgoing payment is denied. |
outgoing_payment.processing | Occurs whenever an outgoing payment is being processed. |
outgoing_payment.confirmed | Occurs whenever an outgoing payment execution is confirmed. |
outgoing_payment.reversed | Occurs whenever an outgoing payment is reversed. |
outgoing_payment.rejected | Occurs whenever an outgoing payment is rejected. |
incoming_payment.created | Occurs whenever Devengo gets notice of the arrival of funds in any of your accounts and create the corresponding incoming payment to represent them. |
incoming_payment.confirmed | Occurs whenever an incoming payment is confirmed after its creation. At this point, the funds are available in your account. |
account.created | Occurs whenever a new account has been created. |
account.activated | Occurs whenever an account created has been activate and can be used. |
account.delayed | Occurs whenever an account has been created but not activated yet due to any incident in the underlying banking infrastructure. |
account.deactivated | Occurs whenever attempts to close an account but we can't due to an issue in the underlying banking infrastructure. |
account.closed | Occurs whenever an account has been closed. |
Webhook security
Basic Auth
One easy way developers can use to provide out-the-box authentication to your webhook listening endpoints is specifying a user and a password in the url provided for the webhook, e.g. http://username:[email protected]. Devengo will honor those params when sending the events to your systems and those will therefore have a simple first layer of protection against unexpected/unauthorized calls.
Webhook signature
In order to provided enhanced security Devengo signs every delivery to your webhooks, including a X-Devengo-Webhooks-Sig
header for each event. This allows you to verify that the events were sent by Devengo, not by an unknown third party.
Before you can verify signatures, you will need your's endpoint's secret. That secret is provided to you when the webhook is created via API or Control Panel. Devengo generates a unique secret key for each endpoint. If you use the same endpoint for both Sandbox and the Production environment, note that the secret will be different for each one. Additionally, if you use multiple endpoints, you must obtain a secret for each one you want to verify signatures on.
Verifying signatures manually
The X-Devengo-Webhooks-Sig
header included in each signed event contains a timestamp and one or more signatures. The timestamp is prefixed by t=, and each signature is prefixed by a scheme. Schemes start with v, followed by an integer. Currently, the only valid live signature scheme is v1.
X-Devengo-Webhooks-Sig:t=1492778686,v1=88fea869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
Devengo generates signatures using a hash-based message authentication code (HMAC) with SHA-256. To prevent downgrade attacks, you should ignore all schemes that are not v1.
Devengo will provide soon support in our official libraries to verify webhook event signatures, but in the meantime you can create a custom solution by following these steps.
Step 1: Extract the timestamp and signatures from the header
Split the header, using the ,
character as the separator, to get a list of elements. Then split each element, using the =
character as the separator, to get a prefix and value pair.
The value for the prefix t
corresponds to the timestamp, and v1
corresponds to the signature (or signatures). You can discard all other elements.
Step 2: Prepare the signed_payload
string
signed_payload
stringThe signed_payload
string is created by concatenating:
- The timestamp (as a string)
- The character .
- The actual JSON payload (that is, the request body)
Step 3: Determine the expected signature
Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the signed_payload string as the message.
Step 4: Compare the signatures
Compare the signature (or signatures) in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.
To protect against timing attacks, use a constant-time string comparison to compare the expected signature to each of the received signatures.