# Configure your webhook server You can configure your webhook server to receive notifications about various events related to your account. For example, payment lifecycle activity, changes to balances, or progress on disputes. --- ## How it works 1. Configure your sever to handle retries and sequencing. 2. Allow Checkout.com IP addresses, if required. 3. Provide the URL you want Checkout.com to send webhooks to using either the Dashboard or the API. You can also build a workflow, with specific actions and conditions, to meet your business needs. 4. Optionally, authenticate each webhook when you receive it on your server using HTTP headers. 5. Validate that the payload was sent by Checkout.com. 6. Acknowledge the webhook. --- ## Handle retries and sequencing Configure your server to handle [automatic retries](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks.md#Automatic_retries). Checkout.com guarantees to send webhooks at least once, but the sequence in which we send them may vary. This means that you may receive webhooks in an unexpected order. We therefore recommend that your webhook server does not rely on the order of webhooks and handles delivery accordingly. --- ## Allow Checkout.com IP addresses In general, Checkout.com does not recommend restricting traffic to a set number of individual IP addresses. If you do so, you must add our IP addresses to your allowlists. > **Information** > > For a list of our IP addresses, see [IP addresses](https://www.checkout.com/docs/developer-resources/ip-addresses.md#Receive_webhook_notifications). --- ## Create a webhook configuration in the Dashboard To provide your webhook URL and create a configuration in the Dashboard, you must have one of the following [user roles](https://www.checkout.com/docs/business-operations/use-the-dashboard/manage-users/user-permissions.md): - Admin - Compliance operator - Developer - A custom role with the following permissions: - `Create, edit and delete workflow notifications` - `View secret keys` - `View the list of workflow notifications` For each configuration, you can subscribe to an unlimited number of event types. 1. Sign in to the [Dashboard](https://dashboard.checkout.com). 2. Select _Developers_ in the left navigation bar and open the _Webhooks_ tab. 3. Select _Create configuration_. 4. Enter a _Name_ for the webhook configuration. 5. Enter the _Endpoint URL_ you want Checkout.com to send webhooks to, prefixed with either `https://` or `http://`. 6. To generate an authorization header key to include in your webhook headers to [validate that Checkout.com sent the webhook](#Validate_the_payload), select _Generate key_. 7. To generate a signature key to hash the webhook payload as an [HMAC](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks.md#Webhook_signatures), select _Generate key_. 8. Optionally, enter an HTTP header _Key_ and _Value_ to pass additional information with webhooks, and select _Add new header_. The header _Value_ can be up to 1,024 characters. 9. Select the checkboxes for event types you want to subscribe to. 10. Select the entities or processing channels you want to receive webhooks for. 11. Select _Create webhook_ to complete your configuration. Checkout.com starts sending the webhooks to which you subscribed to the specified URL immediately. --- ## Add a webhook workflow using the API Call the [Add a workflow](https://api-reference.checkout.com/tag/Workflows/#operation/addWorkflow) endpoint. In the request body, specify the webhook events you want to subscribe to and any actions and conditions. > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `POST` `https://{prefix}.api.checkout.com/workflows` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/workflows` ### Request example ```json withBorder { "name": "My Webhook Workflow", "conditions": [ { "type": "event", "events": { "gateway": [ "payment_approved", "payment_declined", "card_verification_declined", "card_verified", "payment_authorization_incremented", "payment_authorization_increment_declined", "payment_capture_declined", "payment_captured", "payment_refund_declined", "payment_refunded", "payment_void_declined", "payment_voided" ], "dispute": [ "dispute_canceled", "dispute_evidence_required", "dispute_expired", "dispute_lost", "dispute_resolved", "dispute_won" ] } }, { "type": "entity", "entities": ["ent_xyfdshfudosfdshfdiosfds", "ent_fidjosfjdisofdjsifdosfu"] } ], "actions": [ { "type": "webhook", "url": "https://example.com/webhook-receiver", "headers": { "Authorization": "secret-key" }, "signature": { "key": "signature-key" } } ] } ``` ### Response example ```json withBorder { "id": "wf_wlu3wxc26jounofs5iez75qaqa", "_links": { "self": { "href": "https://{prefix}.api.checkout.com/workflows/wf_wlu3wxc26jounofs5iez75qaqa" } } } ``` --- ## Authenticate the webhook You can provide a key in the Authorization HTTP header of every webhook you receive to authenticate it on your server. --- ## Validate the payload To validate that the payload you received was sent by Checkout.com: 1. Hash the payload with the SHA-256 hash function, using your [webhook signature](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks.md#Webhook_signatures) key as the hash key. 2. Compare the resulting HMAC with the one received in the `Cko-Signature` header. If the HMACs are identical, the payload corresponds to what we sent. If the HMACs are different, this indicates that the payload was intercepted and altered. To avoid signature verification inconsistencies, perform the signature calculation based on the raw payload body from the HTTP request. > **Information** > > If you calculate the signature based on a payload that has been deserialized and serialized again, this could change the precision of some values. This is particularly important for payloads that contain special characters. For example,  ©, ®, or ™. --- ## Acknowledge the webhook Your webhook server must acknowledge every webhook it receives within 10 seconds. > **Information** > > If you do not acknowledge a webhook within the time limit, it times out and fails.