> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gnosispay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure webhooks

> Receive asynchronous state changes from Gnosis Pay before you onboard your first user.

Most provisioning and payment operations are asynchronous. For example, a new card is created first and becomes active later. Webhooks tell your backend when these state changes happen.

> [!WARNING]
>
> Configure webhooks **before** you create your first user, so your backend doesn't miss any state changes.

## Set up your endpoint

**1. Register an endpoint**

Call `POST /webhooks` with a public HTTPS URL.

Your endpoint should return a `2xx` response promptly. Move any longer processing to your own queue, so slow work doesn't cause delivery timeouts.

**2. Store the signing key**

`POST /webhooks` returns a `public_key`. Store it securely. If you lose it, you can recover it with `GET /webhooks`.

**3. Verify every request**

Before accepting an event, verify the timestamp and signature headers against the **raw** request body. Parse the body only after verification succeeds, because re-serialized JSON won't match the signature.

**4. Process events idempotently**

Use the event `id` as an idempotency key. The same event can be delivered more than once, so check whether you've already handled an `id` before acting on it.

**5. Read the current resource**

Treat a webhook as a signal that something changed, not as the final state. Events can arrive out of order, after a newer state already exists. When ordering matters, fetch the resource by ID and apply its current state.

## Manage your configuration

| Endpoint | Use it to |
| - | - |
| `GET /webhooks` | Inspect the current configuration and recover your `public_key` |
| `PATCH /webhooks` | Change the URL or pause delivery |
| `DELETE /webhooks` | Stop delivery and remove the configuration entirely |

> [!NOTE]
>
> To stop events temporarily, for example during maintenance, pause delivery with `PATCH /webhooks`. Use `DELETE /webhooks` only when you intend to remove the configuration.

## Next steps

> [card] [Webhook events](https://docs.gnosispay.com/platform-integration/webhook/setup-webhook.md)
>
> See every event type and its payload

> [card] [Onboard a user](https://docs.gnosispay.com/)
>
> Create a KYC profile and start onboarding.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.