---
title: "Register a hook (owners)"
description: "`web`: a signed JSON POST to `url` (see `webhooks` below).\n`buildkite`: Pando calls Buildkite's create-build API,\n`POST https://api.buildkite.com/v2/organizations/{organization}/pipelines/{pipeline}/builds`,\nwith the Worker secret `BUILDKITE_API_TOKEN`, for `push` events (by\ndefault) on branches that are not deleted. The build gets `commit`,\n`branch`, `message`, and `env`: `PANDO_CLONE_URL`, `PANDO_READ_TOKEN`\n(read only, this repo, at least 24 hours: Buildkite's Retry reruns a\njob with this env), `PANDO_STATUS_URL`, `PANDO_STATUS_TOKEN` (posts\nchecks on this commit for 24 hours, stamped `buildkite`; see\ncreateStatus; `pando status <state>` uses it), `PANDO_MONOREPO`,\n`PANDO_REPO`, `PANDO_BRANCH`, `PANDO_HEAD`, `PANDO_DELIVERY`,\n`PANDO_SEQ`. Its `meta_data` has `pando_delivery`, `pando_monorepo`\n(the id) and `pando_repo`, which Pando's Buildkite webhook uses to map\nthe build back (the `ci` tag).\n"
---

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

Path: Pando API › hooks

`POST /v1/monorepos/{owner}/{monorepo}/repos/{repo}/hooks`

`web`: a signed JSON POST to `url` (see `webhooks` below).
`buildkite`: Pando calls Buildkite's create-build API,
`POST https://api.buildkite.com/v2/organizations/{organization}/pipelines/{pipeline}/builds`,
with the Worker secret `BUILDKITE_API_TOKEN`, for `push` events (by
default) on branches that are not deleted. The build gets `commit`,
`branch`, `message`, and `env`: `PANDO_CLONE_URL`, `PANDO_READ_TOKEN`
(read only, this repo, at least 24 hours: Buildkite's Retry reruns a
job with this env), `PANDO_STATUS_URL`, `PANDO_STATUS_TOKEN` (posts
checks on this commit for 24 hours, stamped `buildkite`; see
createStatus; `pando status <state>` uses it), `PANDO_MONOREPO`,
`PANDO_REPO`, `PANDO_BRANCH`, `PANDO_HEAD`, `PANDO_DELIVERY`,
`PANDO_SEQ`. Its `meta_data` has `pando_delivery`, `pando_monorepo`
(the id) and `pando_repo`, which Pando's Buildkite webhook uses to map
the build back (the `ci` tag).

## Authentication

Requires one of the following:

- `credential`, http, header `Authorization`
- `session`, apiKey, in cookie

## Path parameters

- `createHook.path.owner` (string, required) — The monorepo's owner, a namespace (a person's login or an organization). Matched without case.
  - pattern `^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$`
- `createHook.path.monorepo` (string, required) — The monorepo's name within its owner (or an old name). Matched without case.
  - pattern `^[a-z0-9](?:[a-z0-9._]|-(?!-)){0,38}$`
- `createHook.path.repo` (string, required) — The repo's `name` (`projects-web`).

## Request body

_Required._

- `createHook.type` (string, required)
  - one of `"web"`, `"buildkite"`
- `createHook.url` (string, optional) — Required for `web`.
- `createHook.secret` (string, optional) — For `web`, the HMAC key. Write only.
- `createHook.events` (array<string>, optional) — Default `[push, branch.opened, merged, tag]` for web, `[push, merged]` for buildkite (a merge builds main's merge commit).
  - one of `"push"`, `"branch.opened"`, `"merged"`, `"tag"`
- `createHook.buildkite` (object, optional)
  - `createHook.buildkite.organization` (string, required)
  - `createHook.buildkite.pipeline` (string, required)
- `createHook.app` (string, optional) — For `web`: the CI service behind it (`github-actions`, `circleci`, ...), stamped as `app` on statuses posted with its deliveries' status tokens. Not `buildkite` (that is the `buildkite` type's).
  - pattern `^[a-z0-9][a-z0-9-]{0,38}$`

## Example request

```json
{
  "type": "web",
  "url": "string",
  "secret": "string",
  "events": [
    "push"
  ],
  "buildkite": {
    "organization": "string",
    "pipeline": "string"
  },
  "app": "string"
}
```

## Code samples

### cURL

```curl
curl --request POST \
  --url https://app.gitpando.com/v1/monorepos/string/string/repos/string/hooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "web",
  "url": "string",
  "secret": "string",
  "events": [
    "push"
  ],
  "buildkite": {
    "organization": "string",
    "pipeline": "string"
  },
  "app": "string"
}
'
```

### TypeScript

```typescript
const url = 'https://app.gitpando.com/v1/monorepos/string/string/repos/string/hooks';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json', Authorization: 'Bearer <token>'},
  body: JSON.stringify({
    type: 'web',
    url: 'string',
    secret: 'string',
    events: ['push'],
    buildkite: {organization: 'string', pipeline: 'string'},
    app: 'string'
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://app.gitpando.com/v1/monorepos/string/string/repos/string/hooks"

payload = {
    "type": "web",
    "url": "string",
    "secret": "string",
    "events": ["push"],
    "buildkite": {
        "organization": "string",
        "pipeline": "string"
    },
    "app": "string"
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
```

## Responses

### 201

Created

#### Example

```json
{
  "id": "string",
  "type": "web",
  "url": "string",
  "events": [
    "push"
  ],
  "buildkite": {
    "organization": "string",
    "pipeline": "string"
  },
  "app": "string",
  "active": true,
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": "string"
}
```

- `createHook.response.201.id` (string, required)
- `createHook.response.201.type` (string, required)
  - one of `"web"`, `"buildkite"`
- `createHook.response.201.events` (array<string>, required)
  - one of `"push"`, `"branch.opened"`, `"merged"`, `"tag"`
- `createHook.response.201.active` (boolean, required)
- `createHook.response.201.created_at` (string, required)
  - format `date-time`
- `createHook.response.201.url` (string | null, optional)
- `createHook.response.201.buildkite` (object | null, optional)
  - `createHook.response.201.buildkite.organization` (string, optional)
  - `createHook.response.201.buildkite.pipeline` (string, optional)
- `createHook.response.201.app` (string | null, optional) — The app its status tokens stamp: `buildkite` for a buildkite hook, a web hook's own `app`, or null.
- `createHook.response.201.created_by` (string, optional)


Source: https://docs.gitpando.com/api/hooks/createHook/index.md