{"title":"Secure webhooks","category":"default","creationDate":1779533780,"content":"<p>When configuring webhooks for your Adyen implementation, consider our security recommendations to ensure the messages you receive about events are from Adyen, and were not modified during transmission to you.<\/p>\n<h2>Securing webhooks in the Customer Area<\/h2>\n<p>The following video explains ways to secure your webhook in the Customer Area.<\/p>\n<iframe src=\"https:\/\/player.vimeo.com\/video\/843200571\" width=\"640\" height=\"360\" frameborder=\"0\" webkitallowfullscreen mozallowfullscreen allowfullscreen><\/iframe>\n<h2>Authentication \/ Authorization<\/h2>\n<p>We also recommend that you use an authentication mechanism for access to your webhook endpoints to ensure the webhook events you receive were sent by Adyen.<\/p>\n<p>You can use one of the following authentication mechanisms for webhook endpoint access:<\/p>\n<ul>\n<li><strong>Open Authorization (OAuth 2.0)<\/strong>: strongly recommended and supported for the <strong>Standard webhook<\/strong> type<\/li>\n<li><strong>Basic Authentication<\/strong>: supported for all Adyen webhook types<\/li>\n<\/ul>\n<h3>Open Authorization (OAuth 2.0)<\/h3>\n<p><strong>Note:<\/strong> OAuth 2.0 support is available for the <strong>Standard webhook<\/strong> type only.<\/p>\n<p>We strongly recommend that you use OAuth 2.0 for the <strong>Standard webhook<\/strong> type. OAuth 2.0 is a much safer option than basic authentication, ensuring that your server credentials are not compromised.<\/p>\n<p>With an OAuth 2.0 implementation, Adyen requests an OAuth 2.0 access token for sending webhook events to your webhook endpoint. After Adyen obtains an access token from your OAuth 2.0 Identity Provider's authorization server, we send the access token in the header of each webhook event, so you can authenticate the request with your webhook server endpoint.<\/p>\n<p>To <a href=\"\/development-resources\/webhooks\/configure-and-manage#set-up-webhooks-in-your-customer-area\/\">set up OAuth 2.0 for the Standard webhook type<\/a> in your <a href=\"https:\/\/ca-test.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Customer Area<\/a>, you must provide the following:<\/p>\n<ul>\n<li><strong>Client ID<\/strong><\/li>\n<li><strong>Client secret<\/strong> - Make sure to protect your client secret and never embed it in client-side code, as this would expose it to potential misuse.<\/li>\n<li><strong>URL<\/strong>: The location of your OAuth 2.0 Identity Provider's authorization server where Adyen should request new access tokens.<br>At a minimum, the time-to-live (TTL) setting of your access tokens must be one hour (3599 seconds).<\/li>\n<li><strong>Scope<\/strong>: The permission level that Adyen's webhook service needs to access your webhook endpoint.<br>We strongly encourage you to follow the principle of least privilege when creating scopes. Only grant the permissions that are absolutely necessary for your integration.<\/li>\n<\/ul>\n<p>We recommend that you rotate your OAuth 2.0 client credentials periodically to proactively reduce risk and maintain the highest level of security.<\/p>\n<h3>Basic authentication over HTTPS<\/h3>\n<p>For all webhooks types other than the <strong>Standard webhook<\/strong> type, we recommend that you use basic authentication over HTTPS.<\/p>\n<p><strong>Note:<\/strong> You can use basic authentication over HTTPS instead of OAuth 2.0 for the <strong>Standard webhook<\/strong> type. However, basic authentication can leave your server more vulnerable to compromise.<\/p>\n<p>After you have <a href=\"\/development-resources\/webhooks\/configure-and-manage\/#set-up-webhooks-in-your-customer-area\">set up a username and password for basic authentication<\/a> in your <a href=\"https:\/\/ca-test.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Customer Area<\/a>, we include these in the header of the webhook event, so you can authenticate the request with your server. To ensure basic authentication is secure, you must use HTTPS for your webhook endpoint; otherwise your basic authentication credentials can be compromised.<\/p>\n<div class=\"notices yellow\">\n<p>Basic authentication only guarantees that the webhook event was sent by Adyen, not that it wasn't modified during transmission.<\/p>\n<\/div>\n<h2>Hash-based message authentication code (HMAC) signatures<\/h2>\n<p>To protect your server from unauthorized webhooks, we strongly recommend that you use <a href=\"https:\/\/en.wikipedia.org\/wiki\/HMAC\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Hash-based message authentication code<\/a> (HMAC) signatures. By verifying the signature included in a webhook event, you confirm that the event was sent by Adyen, and was not modified during transmission. For more information, refer to <a href=\"\/development-resources\/webhooks\/secure-webhooks\/verify-hmac-signatures\">Verify HMAC signatures<\/a>.<\/p>\n<h3>Changing your HMAC key<\/h3>\n<p>If you need to change the secret HMAC key used to sign webhook events, it is enough to <a href=\"\/development-resources\/webhooks\/secure-webhooks\/verify-hmac-signatures#enable-hmac-signatures\">generate a new HMAC key<\/a> in your <a href=\"https:\/\/ca-test.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Customer Area<\/a>.<\/p>\n<p>If you generate a new HMAC key, it can take some time to propagate this in our infrastructure, so make sure that you can still accept webhook events signed with your previous HMAC key for some time.<\/p>\n<h2>Domain and IP addresses<\/h2>\n<p>Depending on your network and security requirements, you might need to add Adyen's network to your firewall's allowlist to receive <a href=\"\/development-resources\/webhooks\/webhook-types\/\">webhook events<\/a> from us.<\/p>\n<p>We do not provide a list of IP addresses. IP addresses change over time due to various reasons, such as ISP configuration changes. This can lead to disruptions in receiving webhooks if IP addresses are hard-coded.<\/p>\n<p><\/p>\n<p>To make sure you can communicate with our network, you can either:<\/p>\n<ul>\n<li><strong>Use a domain allowlist<\/strong>. Include our domain <code>out.adyen.com<\/code> if your network configuration allows domain allowlisting.<\/li>\n<li><strong>Systematically resolve our IP addresses<\/strong>. Perform DNS lookup for <code>out.adyen.com<\/code>. We recommend that you check every hour. However, if you choose to hardcode the resolved IP addresses to an allowlist, you still run the risk of a disruption if IP addresses change during the DNS lookup interval.<\/li>\n<\/ul>","url":"https:\/\/docs.adyen.com\/development-resources\/webhooks\/secure-webhooks","articleFields":{"description":"Learn about best practices for securing your webhooks.","feedback_component":true,"page_id":"5b88e10e-2d2f-4fe9-834d-4d3c0ff809ae","filters_component":false,"decision_tree":"[]"},"algolia":{"url":"https:\/\/docs.adyen.com\/development-resources\/webhooks\/secure-webhooks","title":"Secure webhooks","content":"When configuring webhooks for your Adyen implementation, consider our security recommendations to ensure the messages you receive about events are from Adyen, and were not modified during transmission to you.\nSecuring webhooks in the Customer Area\nThe following video explains ways to secure your webhook in the Customer Area.\n\nAuthentication \/ Authorization\nWe also recommend that you use an authentication mechanism for access to your webhook endpoints to ensure the webhook events you receive were sent by Adyen.\nYou can use one of the following authentication mechanisms for webhook endpoint access:\n\nOpen Authorization (OAuth 2.0): strongly recommended and supported for the Standard webhook type\nBasic Authentication: supported for all Adyen webhook types\n\nOpen Authorization (OAuth 2.0)\nNote: OAuth 2.0 support is available for the Standard webhook type only.\nWe strongly recommend that you use OAuth 2.0 for the Standard webhook type. OAuth 2.0 is a much safer option than basic authentication, ensuring that your server credentials are not compromised.\nWith an OAuth 2.0 implementation, Adyen requests an OAuth 2.0 access token for sending webhook events to your webhook endpoint. After Adyen obtains an access token from your OAuth 2.0 Identity Provider's authorization server, we send the access token in the header of each webhook event, so you can authenticate the request with your webhook server endpoint.\nTo set up OAuth 2.0 for the Standard webhook type in your Customer Area, you must provide the following:\n\nClient ID\nClient secret - Make sure to protect your client secret and never embed it in client-side code, as this would expose it to potential misuse.\nURL: The location of your OAuth 2.0 Identity Provider's authorization server where Adyen should request new access tokens.At a minimum, the time-to-live (TTL) setting of your access tokens must be one hour (3599 seconds).\nScope: The permission level that Adyen's webhook service needs to access your webhook endpoint.We strongly encourage you to follow the principle of least privilege when creating scopes. Only grant the permissions that are absolutely necessary for your integration.\n\nWe recommend that you rotate your OAuth 2.0 client credentials periodically to proactively reduce risk and maintain the highest level of security.\nBasic authentication over HTTPS\nFor all webhooks types other than the Standard webhook type, we recommend that you use basic authentication over HTTPS.\nNote: You can use basic authentication over HTTPS instead of OAuth 2.0 for the Standard webhook type. However, basic authentication can leave your server more vulnerable to compromise.\nAfter you have set up a username and password for basic authentication in your Customer Area, we include these in the header of the webhook event, so you can authenticate the request with your server. To ensure basic authentication is secure, you must use HTTPS for your webhook endpoint; otherwise your basic authentication credentials can be compromised.\n\nBasic authentication only guarantees that the webhook event was sent by Adyen, not that it wasn't modified during transmission.\n\nHash-based message authentication code (HMAC) signatures\nTo protect your server from unauthorized webhooks, we strongly recommend that you use Hash-based message authentication code (HMAC) signatures. By verifying the signature included in a webhook event, you confirm that the event was sent by Adyen, and was not modified during transmission. For more information, refer to Verify HMAC signatures.\nChanging your HMAC key\nIf you need to change the secret HMAC key used to sign webhook events, it is enough to generate a new HMAC key in your Customer Area.\nIf you generate a new HMAC key, it can take some time to propagate this in our infrastructure, so make sure that you can still accept webhook events signed with your previous HMAC key for some time.\nDomain and IP addresses\nDepending on your network and security requirements, you might need to add Adyen's network to your firewall's allowlist to receive webhook events from us.\nWe do not provide a list of IP addresses. IP addresses change over time due to various reasons, such as ISP configuration changes. This can lead to disruptions in receiving webhooks if IP addresses are hard-coded.\n\nTo make sure you can communicate with our network, you can either:\n\nUse a domain allowlist. Include our domain out.adyen.com if your network configuration allows domain allowlisting.\nSystematically resolve our IP addresses. Perform DNS lookup for out.adyen.com. We recommend that you check every hour. However, if you choose to hardcode the resolved IP addresses to an allowlist, you still run the risk of a disruption if IP addresses change during the DNS lookup interval.\n","type":"page","locale":"en","boost":17,"hierarchy":{"lvl0":"Home","lvl1":"Development resources","lvl2":"Webhooks","lvl3":"Secure webhooks"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/development-resources","lvl2":"https:\/\/docs.adyen.com\/development-resources\/webhooks","lvl3":"\/development-resources\/webhooks\/secure-webhooks"},"levels":4,"category":"Development Resources","category_color":"green","tags":["Secure","webhooks"]}}