# Guide to Texture Webhooks: Features and Best Practices

[Texture](https://www.texturehq.com) connects energy devices (home batteries, EV chargers, solar inverters, thermostats and vehicles) through one API, so utilities and energy companies can read device data and send commands across manufacturers. Its webhooks report what happens in a workspace: devices being discovered, updated or going offline, commands succeeding, failing or being overridden, and new customers, sites and programme enrolments.

This guide covers creating a Texture webhook destination, the two naming schemes for events, the shared payload fields and redaction, verification of `Texture-Signature` with a `whsec_`-style secret, and how to handle retries and out-of-order delivery.

## What are Texture webhooks?

A Texture webhook is a **destination** in a workspace. It has a label, a URL, optional custom headers, the event types it subscribes to, an optional device-type scope and optional redaction of location or contact data. You can create several, for example one per environment, from the dashboard or with the [destinations API](https://docs.texturehq.com/management-api/destinations).

Each delivery is a JSON `POST` with a `Texture-Signature` header and a `Texture-Timestamp` header. Texture asks for a `2xx` within 10 seconds and retries failures, but it doesn't publish the retry schedule and warns that persistent failures can lose events. It also warns that events can arrive out of order.

## Texture webhook features

| Feature | Details |
| --- | --- |
| Signature | hex HMAC-SHA256 |
| Signature header | `texture-signature` |
| Body | JSON |
| Event routing | Body field `type` |

## Events and payloads

| Event | Triggered When | Common Use Cases |
| --- | --- | --- |
| `device.discovered` | A new device is discovered | Register the device in your system |
| `device.updated` | Device data is updated | Sync state, update dashboards |
| `device.disconnected` | A device goes offline | Alert operations, pause automation |
| `command.succeeded` | A device command succeeds | Mark a dispatch or schedule complete |
| `command.failed` | A device command fails | Retry or alert |
| `command.overridden` | A device command is overridden | Reconcile expected vs actual state |
| `customer.created` | A customer is created | Create the matching account |
| `enrollment.approved` | An enrolment is approved | Start programme onboarding |
| `site.created` | A site is created | Link the site to your records |

Texture uses two vocabularies. When creating a destination you subscribe with UPPER_SNAKE names such as `DEVICE_UPDATED` or `COMMAND_SUCCEEDED`. On the wire, `type` uses the dotted form, `device.updated`. There are 20 subscription names but only nine documented wire types, so events such as `ALERT_CREATED` will arrive with a `type` you'll need to discover. The `device.created` example on Texture's webhooks page isn't in either list. Event names use a dot, while commands you send to devices use a colon (`noun:verb`).

### Event Payload Structure

All events share:

* `type`, the dotted event name
* `deviceId`, the device the event concerns
* `organizationId` and `workspaceId`, which tell you where an event came from when several workspaces post to one URL

Texture's events page adds three more: `version`, a semantic version for the event's shape; `key`, a hash of the event data intended for deduplication; and `timestamp`. The remaining fields depend on the event and the device type, and Texture doesn't publish a full example body.

With `redactCategories` set to `LOCATION` or `CONTACT`, those fields are left out of the body altogether, so code that reads addresses or contact details must treat them as optional. The signature covers the redacted body you actually receive.

## Setting up Texture webhooks

### Prerequisites

* A Texture workspace where you can manage destinations
* A public HTTPS endpoint. Texture delivers from the cloud, so `localhost` is unreachable; use the Hookdeck CLI during development

### Get Your Signing Secret

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

1. Create or open a webhook destination in the dashboard, or use the destinations API.
2. Set `secret` to any string, such as `whsec_my-webhook-secret`, or leave it empty and Texture generates one.
3. Store the full value as `WEBHOOK_SECRET`. Don't strip `whsec_` and don't base64-decode it.

The prefix looks like a Standard Webhooks key, and Texture's events page even claims compatibility with that specification, but the documented scheme is different. A Standard Webhooks library will fail against Texture deliveries.

### Register Your Endpoint

1. Give the destination a **Label** and the **URL**, for example `https://example.com/webhooks/texture`.
2. Add any **Headers** you want sent with every request.
3. Choose the event types, e.g. `["DEVICE_UPDATED", "COMMAND_SUCCEEDED", "CUSTOMER_CREATED"]`, and optionally a device type: `ALL`, `BATTERIES`, `CHARGERS`, `SOLAR_INVERTERS`, `THERMOSTATS` or `VEHICLES`.
4. Set `redactCategories` if your receiver shouldn't hold location or contact data.

### Test a delivery

Start a local receiver and forward requests with the [Hookdeck CLI](/docs/cli):

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

```

Create a destination for the CLI URL subscribed to `DEVICE_UPDATED`, then connect or refresh a test device. Note the `type`, `key`, `version` and device-specific fields in the first body, and check which fields disappear when you turn on redaction.

## Securing Texture webhooks

`Texture-Signature` is the hex HMAC-SHA256 of the raw body, keyed with the destination secret exactly as stored, `whsec_` included. Texture's sample signs `JSON.stringify(payload)`, but the docs also stress that order and whitespace matter, so always verify the received bytes rather than re-serialising. `Texture-Timestamp` (Unix milliseconds) isn't part of the signature. See [webhook signature verification](https://docs.texturehq.com/management-api/destinations#webhook-signature-verification).

### Node.js verification

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

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const signature = headers['texture-signature'];
  if (typeof signature !== 'string') return false;
  const key = Buffer.from(secret, 'utf8');
  const message = rawBody;
  const candidates = [signature];
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
    const received = Buffer.from(candidate, 'hex');
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

```

The handler deduplicates on the event `key`, then checks `timestamp` against the last event stored for the same device and type so an older `device.updated` can't overwrite newer state.

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

function createTextureApp({ claimKey, latestEventTime, applyEvent }) {
  const app = express();
  app.post('/webhooks/texture', express.raw({ type: '*/*' }), async (req, res) => {
    const secret = process.env.WEBHOOK_SECRET;
    if (!secret) return res.sendStatus(500);
    if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
    let event;
    try {
      event = JSON.parse(req.body.toString('utf8'));
    } catch {
      return res.sendStatus(400);
    }
    if (!event || typeof event !== 'object' || Array.isArray(event)) return res.sendStatus(400);
    if (!event.key || typeof event.type !== 'string') return res.sendStatus(400);
    const eventTime = typeof event.timestamp === 'number' ? event.timestamp : Date.parse(event.timestamp);
    try {
      if (!(await claimKey(event.key))) return res.sendStatus(200);
      const latest = await latestEventTime(event.deviceId, event.type);
      if (event.deviceId && latest && eventTime < latest) return res.sendStatus(200);
      await applyEvent(event.type, event);
    } catch {
      return res.sendStatus(503);
    }
    return res.sendStatus(200);
  });
  return app;
}

```

`applyEvent` should accept unknown `type` values and log them, given how many subscription names have no documented wire type.

A Hookdeck Texture source computes the same hex HMAC with the secret as a literal key. It responds `200` to Texture in every case. If the digest is wrong, Hookdeck records the request as failed verification and stops there. Because the timestamp isn't signed, Hookdeck doesn't check its age.

> **Keep device state accurate.** [Hookdeck Event Gateway](/event-gateway) verifies Texture's signature, responds well within 10 seconds and keeps every device and command event available for retry and replay.

## Texture webhook limitations and pain points

### Retries with no published schedule

**The Problem:** You can't tell how long your endpoint can be down before events are lost.

**Why It Happens:** Texture retries failed deliveries but documents neither the attempt count nor the spacing, and says persistent failures may lose events.

**Workarounds:**

* Keep the endpoint highly available and respond quickly.
* After an outage, re-read device and command state from Texture's API.

**How Hookdeck Can Help:** Hookdeck acknowledges each event as soon as it arrives and holds it, retrying your service on a schedule you choose.

### Out-of-order events

**The Problem:** An older update can arrive after a newer one and overwrite current device state.

**Why It Happens:** Texture states that events may arrive out of order.

**Workarounds:**

* Compare `timestamp` per device and event type before applying an update.
* For command results, check the command's current status before acting on a stale event.

**How Hookdeck Can Help:** Hookdeck keeps each event's original body and arrival time, which makes ordering problems easy to investigate.

### Two naming schemes and missing wire types

**The Problem:** Subscribing to an event doesn't tell you what its `type` will be.

**Why It Happens:** Subscriptions use UPPER_SNAKE names, wire events use dotted names, and 11 of the 20 subscription names have no documented dotted equivalent.

**Workarounds:**

* Subscribe only to events whose wire type you've confirmed in testing.
* Log unknown `type` values with the subscription that produced them.

**How Hookdeck Can Help:** Hookdeck's request log shows the actual `type` of every delivery, and filters can route each one to the right handler.

### Misleading Standard Webhooks claim

**The Problem:** Teams reach for a Standard Webhooks library and every verification fails.

**Why It Happens:** The events page claims Standard Webhooks compatibility and the example secret starts with `whsec_`, but the signature is a bare hex HMAC in `Texture-Signature`, with no `webhook-id` and a secret that isn't base64-decoded.

**Workarounds:**

* Use a plain HMAC-SHA256 check as shown above.

**How Hookdeck Can Help:** Hookdeck's Texture source implements Texture's actual scheme, so there's nothing to adapt.

### No replay protection

**The Problem:** A captured request still verifies if sent again later.

**Why It Happens:** `Texture-Timestamp` isn't signed, so its value can't be trusted for freshness.

**Workarounds:**

* Deduplicate on `key` and keep the record for longer than any plausible retry period.

**How Hookdeck Can Help:** Deduplication on the Hookdeck connection can discard repeats of the same body before they reach you.

## Best practices

### Use redaction where you can

If a consumer only needs device telemetry, set `redactCategories` to `LOCATION` and `CONTACT` on its destination. Data that never arrives doesn't need protecting.

### Separate destinations by consumer

Give each environment or service its own destination, secret and device-type scope. It limits what each one receives and makes rotation independent.

### Check version before parsing

Read `version` and route to a parser for that shape. Log versions you haven't seen before.

### Treat command events as the source of truth

Use `command.succeeded`, `command.failed` and `command.overridden` to close out dispatches, rather than assuming a command worked because the API accepted it.

## Conclusion

Texture's webhooks cover the full life of energy devices and the commands sent to them, with useful controls for scope and redaction. Receivers have to work around a few rough edges: a secret that looks like Standard Webhooks but isn't, event types that only partly match their subscription names, an unsigned timestamp, out-of-order delivery and an unpublished retry policy.

[Hookdeck Event Gateway](https://hookdeck.com) adds reliable retries, replay and deduplication in front of your Texture integration.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle Texture webhooks reliably in minutes.