What this is: a step you can add to any Automation flow to call an external HTTP endpoint. Use it to push a contact into your CRM, kick off a job in your own backend, or notify a service that Textmagic has no built-in integration for.

The step sends one request per contact that reaches it, waits for the response, and records both in the run log. It signs every request so your endpoint can prove the call really came from Textmagic, and it can carry contact data through placeholders.

At a glance

Methods

GET, POST, PUT, PATCH, DELETE

Body formats

JSON, form, plain text

Authentication

Bearer, Basic, API key

Signing

HMAC-SHA256, Standard Webhooks

Timeout

10 seconds

Retries

Up to 3, optional

Limits and boundaries

Worth reading before you design around the step — most of these cannot be raised.

Step fields

What each control in the step editor does.

Contact placeholders

Wrap a field name in single braces and it is replaced with that contact’s value at send time: {First Name}, {Last Name}, {Company Name}, {Phone}, {Email}, plus any custom field by its exact title.

A JSON body carrying the standard contact fields:

{
  "firstName": "{First Name}",
  "lastName":  "{Last Name}",
  "company":   "{Company Name}",
  "phone":     "{Phone}",
  "email":     "{Email}"
}

Authentication

Four options. In all three authenticated modes the credential itself is encrypted at rest and never appears in the automation, the run log, or an export — only a masked hint does.

API key placement

The key name is the field the key travels in, not the key itself. With placement set to Header a key named X-Api-Key is sent as X-Api-Key: <value>; with Query a key named api_key is appended as ?api_key=<value> alongside your own parameters.

Headers and query parameters

Reserved header names

These are set by the sender and cannot be defined on the step:

Precedence

If a header you defined collides with one the sender sets, the sender wins. Authentication is applied after your headers, and the signature after that, so a step can neither forge nor suppress them.

Webhook signing

Anyone can POST to a public URL. Signing lets your endpoint tell a genuine Textmagic request from a forged one. Generate a signing secret on the step and three headers are added to every request.

How the signature is built

Textmagic implements the Standard Webhooks specification, so an off-the-shelf library will verify it — you do not have to write the code below if you already use one.

• The signed content is the three parts joined by dots: {webhook-id}.{webhook-timestamp}.{raw body}
• The key is the secret with its whsec_ prefix removed and the remainder base64-decoded — the key is those raw bytes, not the printable string.
• The signature is HMAC-SHA256 over the signed content, base64-encoded, prefixed with v1,.

A signed request on the wire:

POST /hooks/textmagic HTTP/1.1
host: api.example.com
content-type: application/json
webhook-id: msg_2f7a1c94e3b8
webhook-timestamp: 1757930400
webhook-signature: v1,g3sVlP0K2mQ8tRz7YxJhN1cW5bF4dE6aU9oI3pL2sK0=

{"firstName":"Bruce","email":"[email protected]"}

Verifying a signature

Four language examples below. Pick the one you need — the logic is identical in every language.

PHP

// $body must be the raw request body, exactly as received.
function verifyTextmagicWebhook(string $secret, array $headers, string $body): bool
{
    $id        = $headers['webhook-id'] ?? '';
    $timestamp = $headers['webhook-timestamp'] ?? '';
    $header    = $headers['webhook-signature'] ?? '';

    if ($id === '' || $timestamp === '' || $header === '') {
        return false;
    }

    // Reject anything older or newer than five minutes.
    if (abs(time() - (int) $timestamp) > 300) {
        return false;
    }

    $key = base64_decode(substr($secret, strlen('whsec_')), true);
    if ($key === false) {
        return false;
    }

    $expected = base64_encode(
        hash_hmac('sha256', "$id.$timestamp.$body", $key, true)
    );

    foreach (explode(' ', $header) as $entry) {
        [$version, $signature] = array_pad(explode(',', $entry, 2), 2, '');

        if ($version === 'v1' && hash_equals($expected, $signature)) {
            return true;
        }
    }

    return false;
}

Node.js

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

// body must be the raw request body as a string or Buffer, not a parsed object.
function verifyTextmagicWebhook(secret, headers, body) {
  const id = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  const header = headers['webhook-signature'];

  if (!id || !timestamp || !header) return false;

  // Reject anything older or newer than five minutes.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const expected = crypto
    .createHmac('sha256', key)
    .update(`${id}.${timestamp}.${body}`)
    .digest('base64');

  return header.split(' ').some((entry) => {
    const [version, signature] = entry.split(',');
    if (version !== 'v1' || !signature) return false;

    const a = Buffer.from(expected);
    const b = Buffer.from(signature);

    return a.length === b.length && crypto.timingSafeEqual(a, b);
  });
}

Python

import base64
import hashlib
import hmac
import time


# body must be the raw request bytes, before any JSON parsing.
def verify_textmagic_webhook(secret: str, headers: dict, body: bytes) -> bool:
    message_id = headers.get("webhook-id", "")
    timestamp = headers.get("webhook-timestamp", "")
    header = headers.get("webhook-signature", "")

    if not (message_id and timestamp and header):
        return False

    # Reject anything older or newer than five minutes.
    if abs(time.time() - int(timestamp)) > 300:
        return False

    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{message_id}.{timestamp}.".encode() + body
    expected = base64.b64encode(
        hmac.new(key, signed, hashlib.sha256).digest()
    ).decode()

    for entry in header.split(" "):
        version, _, signature = entry.partition(",")

        if version == "v1" and hmac.compare_digest(expected, signature):
            return True

    return False

Go

package webhook

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/base64"
	"fmt"
	"net/http"
	"strconv"
	"strings"
	"time"
)

// body must be the raw request body, read before any decoding.
func Verify(secret string, header http.Header, body []byte) bool {
	id := header.Get("webhook-id")
	timestamp := header.Get("webhook-timestamp")
	signatures := header.Get("webhook-signature")

	if id == "" || timestamp == "" || signatures == "" {
		return false
	}

	sent, err := strconv.ParseInt(timestamp, 10, 64)
	if err != nil {
		return false
	}

	// Reject anything older or newer than five minutes.
	if drift := time.Now().Unix() - sent; drift > 300 || drift < -300 {
		return false
	}

	key, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_"))
	if err != nil {
		return false
	}

	mac := hmac.New(sha256.New, key)
	fmt.Fprintf(mac, "%s.%s.", id, timestamp)
	mac.Write(body)
	expected := base64.StdEncoding.EncodeToString(mac.Sum(nil))

	for _, entry := range strings.Split(signatures, " ") {
		version, signature, found := strings.Cut(entry, ",")

		if found && version == "v1" && hmac.Equal([]byte(expected), []byte(signature)) {
			return true
		}
	}

	return false
}

Three checks worth making

• Compare in constant time. hash_equals, timingSafeEqual, compare_digest, hmac.Equal — never == on the signature string.
• Enforce a timestamp window. Five minutes is the usual choice. Without it, a captured request stays replayable forever.
• Deduplicate on webhook-id. A retry carries the same id with a fresh timestamp and signature. If your handler is not idempotent, record the ids you have processed.

Delivery and retries

Any 2xx is a success. Everything else — a non-2xx status, a connection failure, a timeout — is a failure, and what happens next depends on the retry setting.

With retries on

Four attempts in total, on a widening interval:

Timeouts

Each attempt is bounded at 10 seconds, covering connection, TLS handshake and the complete response. If your endpoint does real work, acknowledge the request immediately and process it in the background — that is standard practice for webhook receivers and keeps you well inside the window.

What the run log shows

Open any run of the automation and the webhook step records the method, the URL, the response status, and the outcome. Both the request body that was actually sent — placeholders already substituted — and the response body are available to download.

• Bodies are capped at 16 KB each in the log. Your endpoint still receives the complete request.
• Downloads are plain files, never rendered in the browser — a response from your endpoint is not treated as trusted content.
• Everything is removed with the run log after 12 months.

Error reference

What you will see in the run log when a step fails, and what to do about it.

Security

Credentials at rest — Tokens, passwords, API keys and signing secrets are encrypted. The step stores a reference, never the value.

Shown once — A generated signing secret is displayed at creation only. Afterwards you see a masked hint.

No redirects — Redirect responses are never followed, so credentials cannot be carried to another host.

Public destinations only — Private, loopback and cloud metadata addresses are refused, checked after DNS resolution.

Reserved headers — A step cannot override the headers that carry authentication or the signature.

Transport — Use https. Plain http is accepted for internal testing, but sends your credential in the clear.