Gareth Wilson Gareth Wilson

Guide to Texture Webhooks: Features and Best Practices

Published


Texture 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.

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

FeatureDetails
Signaturehex HMAC-SHA256
Signature headertexture-signature
BodyJSON
Event routingBody field type

Events and payloads

EventTriggered WhenCommon Use Cases
device.discoveredA new device is discoveredRegister the device in your system
device.updatedDevice data is updatedSync state, update dashboards
device.disconnectedA device goes offlineAlert operations, pause automation
command.succeededA device command succeedsMark a dispatch or schedule complete
command.failedA device command failsRetry or alert
command.overriddenA device command is overriddenReconcile expected vs actual state
customer.createdA customer is createdCreate the matching account
enrollment.approvedAn enrolment is approvedStart programme onboarding
site.createdA site is createdLink 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:

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.

Node.js verification

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.

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 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 adds reliable retries, replay and deduplication in front of your Texture integration.

Get started with Hookdeck for free and handle Texture webhooks reliably in minutes.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.