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

# Receive webhooks securely

> Register HTTPS endpoints, verify signatures, and process idempotent events.

Webhooks notify your system about payments, links, refunds, payouts, and capabilities. Verify each delivery before applying effects.

## Register an endpoint

`POST /v1/webhook_endpoints` requires an HTTPS URL and a closed event list. Creation also requires idempotency and step-up where applicable.

## Process each delivery

<Steps>
  <Step title="Read the unmodified body">
    Preserve the exact bytes received from SimplePay.
  </Step>

  <Step title="Verify signature and timestamp">
    Reject invalid signatures and timestamps outside the tolerance.
  </Step>

  <Step title="Deduplicate the event">
    Insert the event ID under a unique constraint before applying effects.
  </Step>

  <Step title="Respond promptly">
    Persist the event and return `2xx`. Queue expensive work durably.
  </Step>
</Steps>

You can list, retrieve, update, and delete endpoints. Secret rotation returns the new secret once.

<Danger>
  Verifying reserialized JSON breaks the signature contract. Always use the
  original body.
</Danger>