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

# Set Up Partner Webhooks

> Register your partner endpoint, verify an event, and read what it's about

A partner has one webhook endpoint. It receives the events of every payment transaction created with the partner's credential, while the merchant is still with the partner, and its merchants' status changes.

| # | Step | Who |
| - | - | - |
| 1 | Check whether you have an endpoint | API |
| 2 | Create it, and store its signing secret | API |
| 3 | Receive an event, and verify its signature | Quidkey sends it |
| 4 | Read the resource the event names | API |

**1. Check for an endpoint**

```bash theme={null}
curl 'https://api.quidkey.com/v1/partners/p_1/webhook-endpoints' \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

The list holds your endpoint, or is empty when you have none.

**2. Create the endpoint**

```bash theme={null}
curl -X POST 'https://api.quidkey.com/v1/partners/p_1/webhook-endpoints' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Idempotency-Key: "6f1d7a52-0f3c-4c8e-9a51-2a7d5b8c9e10"' \
  -H 'Content-Type: application/json' \
  -d '{ "url": "https://api.example.com/webhooks/quidkey" }'
```

```json Response theme={null}
{
  "result": {
    "_type": "webhook_endpoint",
    "_uri": "/webhook-endpoints/we_1",
    "_view": "full",
    "id": "we_1",
    "owner": { "_type": "partner", "id": "p_1" },
    "name": null,
    "url": "https://api.example.com/webhooks/quidkey",
    "is_signed": true,
    "status": "active",
    "is_default": false,
    "signing_secret": "whsec_YOUR_SIGNING_SECRET",
    "created_at": "2026-11-02T10:00:00.000Z",
    "updated_at": "2026-11-02T10:00:00.000Z"
  },
  "entities": {},
  "not_included": []
}
```

Store `signing_secret` now: it isn't shown again. If the answer has no `signing_secret`, as a replay doesn't, `POST /webhook-endpoints/{id}:rotateSecret` issues one. A partner endpoint is always signed. A second endpoint answers 409 `PARTNER_WEBHOOK_ENDPOINT_EXISTS`: change the one you have with `PATCH /webhook-endpoints/{id}`, and replace its secret with `POST /webhook-endpoints/{id}:rotateSecret`.

**3. Receive and verify an event**

Quidkey posts each event to your endpoint, signed in `X-Signature`. Verify it with the signing secret before you parse it, as [Webhooks](https://docs.quidkey.com/api-v1/webhooks.md#verify-every-event) shows. De-duplicate on `result.id`.

**4. Read the resource**

The event's `result.subject` names what it's about. Read it at the path its `id` gives, never at a URL taken from the body:

| `result.type` | `result.subject` | Read |
| - | - | - |
| `transaction.payment.*` | The payment transaction | `GET /transactions/{result.subject.id}` |
| `transaction.reversal.*` | The reversal | `GET /transactions/{result.subject.id}` |
| `merchant.*` | The merchant | `GET /merchants/{result.subject.id}` |

A payment transaction created with a merchant's own credential reports to the merchant's endpoints instead. See [Integrate as a merchant](https://docs.quidkey.com/api-v1/journeys/merchant-integration.md).


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