Agent skill
Texture Webhooks Skill
Receive and verify Texture webhooks. Use when setting up a Texture webhook destination, debugging Texture-Signature verification failures, or handling energy-device events like device.updated, command.succeeded, customer.created and enrollment.approved.
Install this skill
npx skills add hookdeck/webhook-skills --skill 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-Signatureheader? - 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.succeededorcustomer.createdevents?
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):
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.
For complete handlers with tests, see examples/express/, examples/nextjs/, 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
TEXTURE_WEBHOOK_SECRET=whsec_my-webhook-secret # the destination's secret, whole string
Local Development
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 - Event types, payload fields, delivery behavior
- references/setup.md - Creating a webhook destination and getting its secret
- references/verification.md - Signature check in Node, Python and Next.js, gotchas
- examples/ - Runnable Express, Next.js and FastAPI handlers with tests