---
title: "Create a webhook"
description: "POST /v1/webhooks"
canonical: https://www.charitips.com/docs/api-reference/create-webhook
---

# Create a webhook

`POST /v1/webhooks`

**Authentication**: Bearer access token.

## Body

- `target` (string, required, URL): Full url including protocol of the endpoint which will receive the webhooks.
- `events` (string[], required, one of donation_create, donation_update, vote_create, vote_update, recurringdonation_create, recurringdonation_update, campaign_create, campaign_update, charitiesselection_create, charitiesselection_update, paymentmethod_create, charity_publish, charityprofile_update, fiscalreceipt_generated, charity_profile_update, file_generated): List of events to subscribe to. One of `donation_create`, `donation_update`, `vote_create`, `vote_update`, `recurringdonation_create`, `recurringdonation_update`, `campaign_create`, `campaign_update`, `charitiesselection_create`, `charitiesselection_update`, `paymentmethod_create`, `charity_publish`, `charityprofile_update`, `fiscalreceipt_generated`, `charity_profile_update`, `file_generated`.
- `authenticationStrategy` (string, required): Authentication scheme to be used when sending the webhooks to the provided endpoint. One of `BASIC`, `BEARER`.
- `username` (string): Required for Basic authentication.
- `password` (string): Required for Basic authentication.
- `accessToken` (string): Required for Bearer authentication.
- `accountId` (string, UUID): Only required to create the webhook on a child account instead of the current one. Webhooks of a parent account already receive the events of its child accounts.
- `name` (string, required, 2 to 100 characters)

## Response 201

- `webhookId` (string, required)
- `name` (string, required)
- `target` (string, required)
- `events` (string[], required)
- `authenticationStrategy` (WebhookAuthenticationStrategy, required) One of `BASIC`, `BEARER`.
- `accessToken` (string, required)
- `signingKey` (string)
- `accountId` (string, required)
- `createdAt` (string (date-time), required)
- `updatedAt` (string (date-time), required)

## Errors

- 400 `Both username and password are required for Basic authentication`: With authenticationStrategy BASIC, pass the username and password Charitips will send to your endpoint. See https://www.charitips.com/docs/webhooks/configuration.md.
- 400 `accessToken is required for Bearer authentication`: With authenticationStrategy BEARER, pass the accessToken Charitips will send to your endpoint. See https://www.charitips.com/docs/webhooks/configuration.md.
- 400 `Invalid authenticationStrategy`: Set `authenticationStrategy` to `BASIC` (with `username` and `password`) or `BEARER` (with `accessToken`). See https://www.charitips.com/docs/webhooks/configuration.md.
- 400 `A field is missing, has the wrong type, or is not part of the request schema.`: `message` lists every problem. Unknown fields are rejected, not ignored: remove them rather than sending extra data. See https://www.charitips.com/docs/api-reference/errors.md.
- 401 `Unauthorized`: The access token is missing, expired or invalid. Create a new one with your client id and secret, send it as `Authorization: Bearer <accessToken>`, then retry once. Sandbox tokens only work on api.sandbox.charitips.com. See https://www.charitips.com/docs/get-started/authentication.md.
- 402 `Plan upgrade required`: Your plan does not include this feature. Upgrade the plan from the dashboard, then retry. See https://www.charitips.com/docs/overview/plans.md.
- 403 `Account closed`: The account behind these credentials is closed: no token is issued and every call is refused, reads included. Contact Charitips to reopen it. See https://www.charitips.com/docs/api-reference/troubleshooting.md#calls-answer-403-account-not-active-account-not-validated-or-account-closed.

## Example

```bash
curl -X POST https://api.sandbox.charitips.com/v1/webhooks \
  -H "Authorization: Bearer $CHARITIPS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "https://example.com/charitips/webhooks",
    "events": [
      "donation_update"
    ],
    "authenticationStrategy": "BEARER",
    "name": "Donations",
    "accessToken": "<endpointToken>"
  }'
```

```javascript
const response = await fetch('https://api.sandbox.charitips.com/v1/webhooks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CHARITIPS_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "target": "https://example.com/charitips/webhooks",
    "events": [
      "donation_update"
    ],
    "authenticationStrategy": "BEARER",
    "name": "Donations",
    "accessToken": "<endpointToken>"
  }),
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const data = await response.json();
```

```python
import os, requests

response = requests.post(
    "https://api.sandbox.charitips.com/v1/webhooks",
    headers={"Authorization": f"Bearer {os.environ['CHARITIPS_TOKEN']}"},
    json={
      "target": "https://example.com/charitips/webhooks",
      "events": [
        "donation_update"
      ],
      "authenticationStrategy": "BEARER",
      "name": "Donations",
      "accessToken": "<endpointToken>"
    },
)
response.raise_for_status()
data = response.json()
```

## Response example (201, placeholder values)

```json
{
  "webhookId": "<webhookId>",
  "name": "<name>",
  "target": "<target>",
  "events": [],
  "authenticationStrategy": "BASIC",
  "accessToken": "<accessToken>",
  "signingKey": "<signingKey>",
  "accountId": "<accountId>"
}
```