--- updatedAt: 2026-05-28T10:07:09.000Z agentTools: projectIndex: https://docs.devengo.com/llms.txt --- # List Webhooks # OpenAPI definition ````json { "openapi": "3.0.3", "info": { "title": "Devengo API", "version": "1.0.0", "description": "DISCLAIMER: **This is an Insider Preview release of the API. Endpoints and behaviour may still change before the stable 1.0 release.**\n\n## Environments\n\nTo isolate testing and any other exploratory work needed for the development of Devengo API clients, two environments have been configured as follows:\n\n### Sandbox\n\nThis environment simulates the real production environment but never runs actual money transactions. Developers should start working in this environment to explore and integrate their apps before moving to production.\n\nhttps://api.sandbox.devengo.com\n\n### Production\n\nReal environment where the money transactions are performed.\n\nhttps://api.devengo.com\n\n## Idempotency\n\nAs some of the operations with payouts involve not-reversible flows of money, this API supports idempotency keys to prevent the same operation from being accidentally executed twice. This may happen when a request sent by the API client fails due to connection errors or other unexpected conditions. Using the same idempotency key, the API client can safely retry the operation knowing that Devengo will guarantee the operation associated with the key is executed only once.\n\n### How it works\n\nTo perform an idempotent request, provide an additional `X-Devengo-Idempotency-Key` header to the request. When an idempotency key is provided Devengo will save the status code and body of the first request made for that key. Subsequent requests with the same key will return the same status code and body. This approach will be applied regardless of whether the first request succeeded or failed.\n\n### What to use as the key\n\nAn idempotency key is a unique value generated by the client that the server uses to recognize subsequent retries of the same request. Defining the nature and implementing the uniqueness of the keys is up to the client, but Devengo suggests using [V4 UUIDs](https://datatracker.ietf.org/doc/html/rfc4122), or another random string with enough entropy to avoid collisions, like some client business identifier.\n\n### Duration and use of the keys\n\nIdempotency keys will be **stored only for 7 days**. After that period, the key will be removed from the system and a new request will be generated if the old key is reused. The idempotency layer compares incoming parameters to those of the original request and errors unless they're the same to prevent accidental misuse.\n\nAll POST requests accept idempotency keys. Sending idempotency keys in GET and DELETE requests has no effect and should be avoided, as these requests are idempotent by definition.\n\n### How to know when a request was replayed\n\nThe header `Idempotent-Replayed` is attached to every request that is processed as idempotent (POST and PATCH with an `X-Devengo-Idempotency-Key`). It is not returned for GET or DELETE, where the key is ignored.\n\n- `Idempotent-Replayed: false` — this request was executed.\n\n- `Idempotent-Replayed: true` — the status and body are a replay of a previous result for this key, or a conflict because the original attempt is still in progress or has no stored response yet.\n\nThis is the reliable way to distinguish a first execution from a replay.\n\n### Server errors and unknown outcomes\n\nThe first completed response is stored **including 5xx**. A later request with the same key and the same payload, within the 7-day window, returns that stored response and does **not** run the operation again. The key is therefore consumed by a 5xx.\n\nThat does **not** mean the side effect did not happen. Idempotency records the HTTP response; it does not wrap the business operation in a single transaction. A payment can be created and the client can still receive a 5xx, or the connection can drop before the response is stored. In the latter case a retry may receive `409` rather than the original status, and still will not re-execute.\n\nSo:\n\n- Replaying the **same** key cannot create a second payment.\n\n- A stored 5xx or a `409` on that key is **not** proof that no payment exists.\n\n- After a 5xx, a timeout, or a `409` on the key, reconcile before sending the same payment with a **new** key.\n\n### Recovering from an unknown outcome on payment creation\n\nWhen `POST /v1/payments` does not return a clear 2xx or 4xx, do not retry with a different idempotency key until you know whether the payment exists.\n\n1. If you received a `201`, persist the payment `id` and use `GET /v1/payments/{id}`.\n\n2. If the outcome is unknown, call `GET /v1/payments?company_reference=…` using the `company_reference` you sent on create. This filter is supported on the payments listing. `company_reference` is not unique: send a value that is unique per payment attempt so that zero results means the payment was not created, and one result is that payment.\n\n3. You can also rely on `outgoing_payment.*` webhooks if you subscribe to them.\n\nOnly if the listing (and webhooks, if used) show no payment should you create it again, with a new idempotency key.\n\n## Rate Limit Response Headers\n\nAs some endpoints configure API rate limiting, this API provides response headers with rate limited endpoint information if any is configured.\nNowadays entire V1 has a request rate limit configured.\n\nAll Rate Limit Response Headers returned by this API will follow this format:\n\n```\n{\n \"X-RateLimit-Limit\": \"1500\",\n \"X-RateLimit-Remaining\": \"1499\",\n \"X-RateLimit-Reset\": \"1652275233\"\n}\n```\n\n## Standards\n\n### Money\n\nAll amounts of money in this API are represented in cents, followed by the currency code as defined in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html). The following example represents `€ 150.25`:\n\n```\n{\n value: { \"amount\": 15025, \"currency\": \"EUR\" }\n}\n```\n\n### Dates\n\nAll dates in this API are formatted in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.\n\n```\n{\n \"created_at\": \"2019-08-19T14:22:28Z\"\n}\n```\n\n### Countries\n\nAll countries in this API are referenced using the alpha-2 code assigned to them in [ISO 3166](https://www.iso.org/iso-3166-country-codes.html).\n\n```\n{\n \"country\": \"ES\"\n}\n```\n\n### Pagination\n\nAll paginated collections return some extra information in order to allow clients to know the important `links` to navigate the collection, as well as the `total_items` in case the client need to calculate the amount of pages.\n\n```\n\"links\": {\n \"self\": \"https://api.devengo.com/some-collection?page=4&page_size=20\",\n \"first\": \"https://api.devengo.com/some-collection?page=1&page_size=20\",\n \"prev\": \"https://api.devengo.com/some-collection?page=3&page_size=20\",\n \"next\": \"https://api.devengo.com/some-collection?page=5&page_size=20\",\n \"last\": \"https://api.devengo.com/some-collection?page=100&page_size=20\"\n},\n\"meta\": {\n \"pagination\": {\n \"total_items\": 10000\n }\n}\n```\n\n### Errors\n\nAll errors returned by this API will follow this format:\n\n```\n{\n \"error\": {\n \"message\": \"\",\n \"code\": \"\",\n \"type\": \"\"\n }\n}\n```" }, "servers": [ { "url": "https://api.sandbox.devengo.com" } ], "paths": { "/v1/webhooks": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json; charset=utf-8": { "schema": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The id of the webhook." }, "url": { "type": "string", "description": "The URL of the webhook." }, "status": { "type": "string", "enum": [ "enabled", "disabled" ], "description": "Enabled or disabled webhook status." }, "description": { "type": "string", "description": "The description of the webhook.", "nullable": true }, "api_version": { "type": "string", "description": "The API version of the webhook. Value depends on the version the webhook was created with (e.g. `202512`, `202603`).", "nullable": true }, "listened_events": { "description": "Events listened by the webhook. See all the list of available events: https://docs.devengo.com/reference/webhooks-events" } }, "required": [ "id", "url", "status", "description", "api_version", "listened_events" ], "additionalProperties": false } }, "links": { "type": "object", "properties": { "self": { "type": "string" }, "first": { "type": "string" }, "prev": { "type": "string" }, "next": { "type": "string" }, "last": { "type": "string" } }, "required": [ "self", "first", "last" ] }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "total_items": { "type": "number", "description": "The total number of the existing elements of the paginated collection" } } } } } } }, "example": { "webhooks": [ { "id": "whk_QMuQ74NPggjlPWOYbkLdc", "url": "https://devengo.com", "status": "enabled", "description": null, "api_version": null, "listened_events": [] } ], "links": { "self": "https://api.devengo.com/v1/webhooks?page=4&page_size=20", "first": "https://api.devengo.com/v1/webhooks?page=1&page_size=20", "prev": "https://api.devengo.com/v1/webhooks?page=3&page_size=20", "next": "https://api.devengo.com/v1/webhooks?page=5&page_size=20", "last": "https://api.devengo.com/v1/webhooks?page=100&page_size=20" }, "meta": { "pagination": { "total_items": 1000 } } } } } }, "401": { "description": "Unauthorized", "headers": {}, "content": { "application/json; charset=utf-8": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" }, "type": { "type": "string" } } } } }, "example": { "error": { "message": "Signature is invalid", "code": "api_key_signature_invalid", "type": "invalid_signature" } } } } } }, "summary": "List Webhooks", "operationId": "List Webhooks", "description": "", "tags": [ "Webhooks" ], "parameters": [ { "name": "page", "in": "query", "description": "", "example": "1", "schema": { "type": "number" } }, { "name": "page_size", "in": "query", "description": "", "example": "25", "schema": { "type": "number" } }, { "name": "status", "in": "query", "description": "Status of the Webhook. By default, returns all status\n\n+ enabled\n\n+ disabled", "example": "enabled", "schema": { "type": "string" } }, { "name": "X-Devengo-Api-Key-Id", "in": "header", "description": "e.g. tst_apk_53ZrBeMcg3VRtiITAZhgz5", "required": false, "schema": { "type": "string" }, "example": "tst_apk_53ZrBeMcg3VRtiITAZhgz5" }, { "name": "X-Devengo-Api-Key-Nonce", "in": "header", "description": "e.g. f04bc3ba6455738e7ece32c1c25bac8b", "required": false, "schema": { "type": "string" }, "example": "f04bc3ba6455738e7ece32c1c25bac8b" }, { "name": "X-Devengo-Api-Key-Timestamp", "in": "header", "description": "e.g. 1584230400", "required": false, "schema": { "type": "string" }, "example": "1584230400" }, { "name": "X-Devengo-Api-Key-Signature", "in": "header", "description": "e.g. 8PuVvB84Gc60V7dwZx305BpNUHejy6/3ZlPQcIm2s9g=", "required": false, "schema": { "type": "string" }, "example": "8PuVvB84Gc60V7dwZx305BpNUHejy6/3ZlPQcIm2s9g=" } ] } } }, "tags": [ { "name": "Webhooks" } ] } ````