# Texture Webhooks

Texture (texturehq.com), the energy-device data platform, delivers workspace events (devices,
commands, customers, enrollments, sites, alerts) to webhook destinations as an HTTP `POST`.
Each request carries a `Texture-Signature` header: the lowercase hex HMAC-SHA256 of the raw
request body, keyed with the destination's `secret`.

Paste the whole secret, including the whsec_ prefix. Texture uses it as a plain HMAC key.

## When to Use This Skill

* How do I receive Texture webhooks?
* How do I verify the `Texture-Signature` header?
* Why does my Texture webhook signature verification fail?
* Is the Texture `whsec_` secret a Standard Webhooks key? (No, it is a plain HMAC key)
* How do I handle `device.updated`, `command.succeeded` or `customer.created` events?

## Verification (core)

The signature is the bare hex digest (no prefix, no `v1,`), computed over the **raw body bytes
only**. Nothing else is signed: `Texture-Timestamp` is sent but not signed. The key is the
secret's UTF-8 bytes, used as-is (not hex- or base64-decoded):

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

function verifyTextureSignature(rawBody, signature, secret) {
  if (!secret || typeof signature !== 'string') return false;
  if (!/^[0-9a-fA-F]{64}$/.test(signature)) return false; // validate before decoding
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest(); // rawBody: Buffer
  const received = Buffer.from(signature.toLowerCase(), 'hex'); // 32 bytes, safe after the check
  return crypto.timingSafeEqual(expected, received);
}

```

Read the header as `req.headers['texture-signature']` (Node lowercases header names). Return `401`
for a missing, empty or malformed header and for a mismatch. Read the body raw
(`express.raw({ type: '*/*' })`, Next.js `await request.arrayBuffer()`, FastAPI
`await request.body()`) and parse JSON only after the check. Texture's own sample hashes
`JSON.stringify(payload)`, but the docs also say to use the raw payload because order and
whitespace matter: never re-serialize before verifying.

**Do not use the `standardwebhooks` or `svix` libraries.** The secret looks like a Standard
Webhooks `whsec_` secret but is not one: use the whole string, `whsec_` included, as a plain
UTF-8 HMAC key. There is no `webhook-id` and the digest is hex, not base64. No timestamp is
signed, so there is no replay window to enforce; don't invent one from `Texture-Timestamp`.
Python, FastAPI and Next.js versions are in [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/texture-webhooks/references/verification.md).

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

## Event Types

Dispatch on the body's `type` field, which is the dotted name. Destinations *subscribe* with
UPPER_SNAKE names (`DEVICE_UPDATED`), a separate vocabulary that does not appear in `type`.

| `type` | Fired when |
| --- | --- |
| `device.discovered` | A new device is discovered |
| `device.updated` | Device data is updated |
| `device.disconnected` | A device goes offline |
| `command.succeeded` | A device command succeeds |
| `command.failed` | A device command fails |
| `command.overridden` | A device command is overridden |
| `customer.created` | A customer is created |
| `enrollment.approved` | An enrollment is approved |
| `site.created` | A site is created |

Every payload carries `type`, `deviceId`, `organizationId` and `workspaceId`. Handle the ones you
need and log the rest. Texture's docs also show `device.created` in an example, but it is not in
the documented event lists.

## Environment Variables

```bash
TEXTURE_WEBHOOK_SECRET=whsec_my-webhook-secret   # the destination's secret, whole string

```

## Local Development

```bash
npx hookdeck-cli listen 3000 texture --path /webhooks/texture

```

No account required. Use the printed URL as the destination URL in Texture.

## Resources

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/texture-webhooks/references/overview.md) - Event types, payload fields, delivery behavior
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/texture-webhooks/references/setup.md) - Creating a webhook destination and getting its secret
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/texture-webhooks/references/verification.md) - Signature check in Node, Python and Next.js, gotchas
* [examples/](https://github.com/hookdeck/webhook-skills/tree/main/skills/texture-webhooks/examples/) - Runnable Express, Next.js and FastAPI handlers with tests