Getting Started
A guide to learning how to subscribe to Devengo Webhook Events.
When integrating your application with Devengo, staying up-to-date with critical events as they happen becomes essential. This ensures your application always operates with the most current data without continuous API queries.
Webhooks configuration allows you to have one or more URLs that receive the chosen events whenever they happen in Devengo.
This guide will teach you how to create, set up and test Devengo Webhooks.
Create a session token
To interact with the Devengo API, you need to generate a session token. This token authenticates your requests and provides access to the API. To create a new session token, you must provide the email and password used in the signup form.
curl -X POST 'https://api.sandbox.devengo.com/v1/auth/tokens' \
-H 'Content-Type: application/json' \
-d '{"email": "[email protected]", "password": "your_password"}'
{
"token": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX25kIjoibWFuXzRuakRLSTNFQmJjYWtyQXEyMENCSVohLCJ1c2VyX3R5cG6iOiJNYW5hZ2VyIiwiY29xcGFueV9pZCI6bnVsbCwiZXhwIjoiMTY4NjA1MHA0MiJ9.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"refresh_token": "eyJhbGciOiJIvzI1NiJ9.eyJ1c2VyX2lkIjoibWFuXzRuakRLSTNFQmJjYWtyQXEyMENCSVHiLCJ1c2VyX3R5cGUiOiJNYW5hZ2VyIiwiY29tcGFueV9pZCI6bnVsbCwicmVmcmVzaF90b2tlbl9pZCI6InRva18yNUg4ajZHMEFiUUp4VkZHdDJkTWxqIiwiZXhwIjoiMTY4NzI5ODg0MiJ9.IcTS5-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
Create your first Webhook
To create a new Webhook using the Devengo Webhooks API, it's crucial to set up an accessible endpoint to which Devengo can send HTTP POST requests containing event data. During the development and testing phases, you can utilize tools such as ngrok or localtunnel to facilitate this process.
In this example, we'll walk through creating a fresh Webhook that directs events to a RequestBin whenever they occur. To filter and receive specific events exclusively, specify the listened_events array, including one or more events.
curl -X POST https://api.sandbox.devengo.com/v1/webhooks \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer THE_SESSION_TOKEN' \
-d '
{
"url": "https://en53hafv65f7c.x.pipedream.net",
"description": "My webhook example"
}'
{
"webhook": {
"id": "whk_5FNmUoT2xgjNKCqjUpAEaZ",
"url": "https://en53hafv65f7c.x.pipedream.net",
"status": "enabled",
"description": "My webhook example",
"listened_events": [
"account.activated",
"account.closed",
"account.created",
"account.deactivated",
"account.delayed",
"incoming_payment.confirmed",
"incoming_payment.created",
"incoming_payment.rejected",
"outgoing_payment.blocked",
"outgoing_payment.confirmed",
"outgoing_payment.created",
"outgoing_payment.delayed",
"outgoing_payment.denied",
"outgoing_payment.pending",
"outgoing_payment.processing",
"outgoing_payment.rejected",
"outgoing_payment.retrying",
"outgoing_payment.reversed",
"outgoing_payment.validating",
"verification.confirmed",
"verification.created",
"verification.delivered",
"verification.expired",
"verification.failed",
"verification.rejected"
],
"secret": "f0edaa6a1c4a356acffa77389b89405f75e31e77"
}
}
Important: You must store the secret value to be able to verify Devengo messages in your application.
Testing the Webhook
To check if the Webhook is working properly, we need to perform some action on the Sandbox environment. For example, we can create a new account.
curl -X POST 'https://api.sandbox.devengo.com/v1/accounts' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer THE_SESSION_TOKEN' \
--data '{
"name": "Testing webhooks",
"currency": "eur"
}'
After the API responds with a success status, the Webhook URL should receive events for each change in the Account lifecycle update.
{
"id": "evt_4AzCpWGzp4NAJURIwaOwXR",
"api_version": "v1",
"type": "account.created",
"created_at": "2023-08-17T14:27:05Z",
"data": {
"object": {
"id": "acc_4JuSDCyaSckH1N0YC8cH4d",
"status": "active",
"created_at": "2023-08-17T14:27:05Z",
"name": "Testing webhooks",
"bank": {
"name": "Prepaid Financial Services Limited, S.E",
"bic": "PFSSESM1XXX"
},
"identifiers": [
{
"type": "iban",
"iban": "ES9267130002000000000226"
}
],
"currency": "EUR",
"balance": {
"total": {
"cents": 0,
"currency": "EUR"
},
"available": {
"cents": 0,
"currency": "EUR"
}
},
"metadata": {},
"closed_at": null
}
}
}
{
"id": "evt_6OpW1BuH8Jd8NS9C1VMeQ1",
"api_version": "v1",
"type": "account.activated",
"created_at": "2023-08-17T14:27:07Z",
"data": {
"object": {
"id": "acc_4JuSDCyaSckH1N0YC8cH4d",
"status": "active",
"created_at": "2023-08-17T14:27:05Z",
"name": "Testing webhooks",
"bank": {
"name": "Prepaid Financial Services Limited, S.E",
"bic": "PFSSESM1XXX"
},
"identifiers": [
{
"type": "iban",
"iban": "ES9267130002000000000226"
}
],
"currency": "EUR",
"balance": {
"total": {
"cents": 0,
"currency": "EUR"
},
"available": {
"cents": 0,
"currency": "EUR"
}
},
"metadata": {},
"closed_at": null
}
}
}
Best practices for using webhooks
Return a 2XX response
Devengo Webhooks will attempt to deliver events while the Webhook URL does not return a 2XX status. If, for any reason, your system wants to discard an event, respond with a 200 status code and do not process it on your side. Otherwise, Devengo will retry it for days.
Handle events asynchronously
Good practices recommend not processing the event when received but asynchronously in a background job. For example, if your system needs to update the database, it must be done after returning a 200 response.
Event ordering
For many reasons regarding how distributed systems work, Devengo does not guarantee event ordering. You can use the API to fetch the current status for any entity. For example, you can get the Payment status when the payment.created event is received.
Event duplications
Sometimes, your system could receive the same event more than once. It should be able to handle this scenario to prevent errors. You can use event id to know whether it was already processed.
Secure your Webhook integration
It's essential to ensure that the received events are sent from Devengo. Be sure you follow our guide to secure your Webhook endpoints.
Next steps
Updated about 1 year ago