> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.givechariot.com/v2023-01-01/api/event-subscriptions/create/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.givechariot.com/_mcp/server.

# Create an Event Subscription

POST https://api.givechariot.com/v1/event_subscriptions
Content-Type: application/json

Create an event subscription corresponding to your Chariot account.

Reference: https://docs.givechariot.com/api/event-subscriptions/create

## Authentication

- OAuth2 — send the obtained token as `Authorization: Bearer <token>`

## Servers

- `https://api.givechariot.com` (Production, default)
- `https://sandboxapi.givechariot.com` (Sandbox)

## Request

### Body (application/json)

This endpoint expects an object.

- `url` (string, required) — The webhook url where we'll send notifications.
- `category` (enum, required) — The category of the event. This is useful for filtering events.
  - Allowed values: `grant.created`, `grant.updated`, `unintegrated_grant.created`, `unintegrated_grant.updated`
- `signing_secret` (string, optional) — The key that will be used to sign webhooks. If no value is passed, a random string will be used as default. This is necessary to verify that the webhook is coming from Chariot. While this parameter is optional, it is highly recommended to pass a value for the secret and implement webhook signature verification.

## Response

### 201

Created

- `url` (string, required) — The webhook url where we'll send notifications.
- `id` (string, optional) — The unique identifier for the event subscription
- `created_at` (datetime, optional) — The date and time the event subscription was created
- `status` (enum, optional) — The status of the event subscription. This indicates if we'll send notifications to this subscription * active: subscription is active and events will be delivered normally * disabled: subscription is temporarily disabled and events will not be delivered * deleted: subscription has been deleted and events will not be delivered * requires_attention: subscription has been disabled due to delivery failures and events will not be delivered
  - Allowed values: `active`, `disabled`, `deleted`, `requires_attention`
- `category` (enum, optional) — The category of the event. This is useful for filtering events.
  - Allowed values: `grant.created`, `grant.updated`, `unintegrated_grant.created`, `unintegrated_grant.updated`

## Errors

### 400 Bad Request Error

The request is invalid or contains invalid parameters

- `type` (string, required) — A URI reference identifying the problem type.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code for this error.
- `detail` (string, required) — A human-readable explanation specific to this occurrence.

### 401 Unauthorized Error

Unauthorized. The request is missing the security (OAuth2 Bearer token) requirements and the server is unable to verify the identify of the caller.

- `type` (string, required) — A URI reference identifying the problem type.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code for this error.
- `detail` (string, required) — A human-readable explanation specific to this occurrence.

### 403 Forbidden Error

Access denied

- `type` (string, required) — A URI reference identifying the problem type.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code for this error.
- `detail` (string, required) — A human-readable explanation specific to this occurrence.

### 404 Not Found Error

Resource Not Found

- `type` (string, required) — A URI reference identifying the problem type.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code for this error.
- `detail` (string, required) — A human-readable explanation specific to this occurrence.

### 500 Internal Server Error

Internal Server Error

- `type` (string, required) — A URI reference identifying the problem type.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code for this error.
- `detail` (string, required) — A human-readable explanation specific to this occurrence.

## Examples

**Request**

```json
{
  "url": "https://example.com/webhook",
  "category": "grant.created"
}
```

**Response**

```json
{
  "url": "https://example.com/webhook",
  "id": "4d06d393-1f14-46cf-b02d-8db17d7ed06a",
  "created_at": "2024-01-14T12:48:56.37Z",
  "status": "active",
  "category": "grant.created"
}
```