# CompanyCam Webhooks

## When to Use This Skill

* How do I receive CompanyCam webhooks?
* How do I verify the `X-CompanyCam-Signature` header?
* Why is my CompanyCam webhook signature verification failing?
* How do I handle `photo.created`, `project.created`, or `task.completed` events?
* Why are my CompanyCam webhooks unsigned?

## Setup

Set a **token** when you create the CompanyCam webhook (`POST /public_api/v1/webhooks`
with `webhook.url`, `webhook.scopes`, and `webhook.token`). The token is optional on
create, but without one, deliveries are unsigned and fail verification. The token is the
HMAC key; store it as `COMPANYCAM_WEBHOOK_TOKEN`. See [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/companycam-webhooks/references/setup.md).

## Verification (core)

CompanyCam has no webhook verification SDK, so verify manually. The
`X-CompanyCam-Signature` header is `Base64(HMAC-SHA1(token, raw body))`. The algorithm is
SHA-1 and the digest is base64 (not hex). Use the **raw** body; never verify a re-serialized
parse. Compare the base64 strings as equal-length UTF-8 buffers (no lenient base64 decode of
the header).

```javascript
const crypto = require('crypto');

function verifyCompanyCamSignature(rawBody, signature, token) {
  if (!signature || !token) return false;
  const expected = crypto.createHmac('sha1', token).update(rawBody).digest('base64');
  const a = Buffer.from(signature, 'utf8');
  const b = Buffer.from(expected, 'utf8');
  if (a.length !== b.length) return false;       // timingSafeEqual throws on length mismatch
  return crypto.timingSafeEqual(a, b);
}

```

In Python, use `hmac.compare_digest(signature.encode("utf-8"), expected.encode("utf-8"))`
(bytes, so a non-ASCII header returns 401 rather than raising a 500).

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/companycam-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/companycam-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/companycam-webhooks/examples/fastapi/).

In Express, read the body with `express.raw({ type: '*/*' })` so any content type verifies.

## Common Event Types

The event name is in the payload's `event_type` field; the object is in `payload`.

| `event_type` | Triggered When |
| --- | --- |
| `project.created` | A project is created |
| `project.updated` | A project is updated |
| `photo.created` | A photo is created and processed |
| `photo.updated` | A photo is edited (annotations) |
| `comment.created` | A comment is created |
| `document.created` | A document is created for a project |
| `todo_list.completed` | A checklist is completed |
| `task.completed` | A checklist task is completed |

Scopes also include wildcards (`*`, `project.*`, `photo.*`, ...), `project.archived`,
`project.deleted`, `video.created`, and more. See
[references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/companycam-webhooks/references/overview.md).

CompanyCam expects exactly HTTP `200`; any other status is retried with exponential backoff
(max 10 attempts), and a webhook with more than 25 errors is disabled.

## Environment Variables

```bash
COMPANYCAM_WEBHOOK_TOKEN=your_webhook_token   # the `token` you passed when creating the webhook

```

## Local Development

```bash
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 companycam --path /webhooks/companycam

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/companycam-webhooks/references/overview.md) - Webhook concepts, scopes, payload
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/companycam-webhooks/references/setup.md) - Create the webhook with a token
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/companycam-webhooks/references/verification.md) - Signature details and gotchas