Webhooks

Receive inbound texts, keyword opt-ins, and new contacts at your server.

Subscribe to an event, and EZ Texting sends an HTTPS POST to your server whenever it happens.

When to use this guide

Use it when…Use something else when…
You want to react when a contact texts you, opts in with a keyword, or is created.You want delivery status for messages you sent. For that, use message reports → Send, track & receive

Events

Event typeFires whenPayload
inbound_text.receivedA contact texts one of your numbers. Includes replies, STOP/HELP, keyword texts, and MMS.Message
keyword.opt_inA contact texts one of your keywords and is opted in.Keyword opt-in
contact.createdA new contact is created in your account, by any means.Contact

Each subscription is for one event type. Subscribe to two events with two subscriptions.


Subscribe

curl -X POST https://a.eztexting.com/v1/webhooks/subscriptions \
  -u "$EZTEXTING_USERNAME:$EZTEXTING_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "inbound_text.received",
    "callbackUrl": "https://api.example.com/webhooks/eztexting",
    "secret": "a-long-random-string"
  }'
sub = requests.post(
    "https://a.eztexting.com/v1/webhooks/subscriptions",
    auth=auth,
    json={
        "type": "inbound_text.received",
        "callbackUrl": "https://api.example.com/webhooks/eztexting",
        "secret": os.environ["EZTEXTING_WEBHOOK_SECRET"],
    },
    timeout=30,
).json()
const sub = await (await fetch("https://a.eztexting.com/v1/webhooks/subscriptions", {
  method: "POST",
  headers: { Authorization: `Basic ${credentials}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    type: "inbound_text.received",
    callbackUrl: "https://api.example.com/webhooks/eztexting",
    secret: process.env.EZTEXTING_WEBHOOK_SECRET,
  }),
})).json();
<?php
$ch = curl_init("https://a.eztexting.com/v1/webhooks/subscriptions");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv("EZTEXTING_USERNAME") . ":" . getenv("EZTEXTING_PASSWORD"),
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
    CURLOPT_POSTFIELDS => json_encode([
        "type" => "inbound_text.received",
        "callbackUrl" => "https://api.example.com/webhooks/eztexting",
        "secret" => getenv("EZTEXTING_WEBHOOK_SECRET"),
    ]),
]);
$sub = json_decode(curl_exec($ch), true);
curl_close($ch);
uri = URI("https://a.eztexting.com/v1/webhooks/subscriptions")
req = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
req.basic_auth(ENV.fetch("EZTEXTING_USERNAME"), ENV.fetch("EZTEXTING_PASSWORD"))
req.body = {
  type: "inbound_text.received",
  callbackUrl: "https://api.example.com/webhooks/eztexting",
  secret: ENV.fetch("EZTEXTING_WEBHOOK_SECRET")
}.to_json
sub = JSON.parse(Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }.body)
String json = mapper.writeValueAsString(Map.of(
    "type", "inbound_text.received",
    "callbackUrl", "https://api.example.com/webhooks/eztexting",
    "secret", System.getenv("EZTEXTING_WEBHOOK_SECRET")));
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://a.eztexting.com/v1/webhooks/subscriptions"))
    .header("Authorization", "Basic " + basicAuth)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();
JsonNode sub = mapper.readTree(client.send(request, HttpResponse.BodyHandlers.ofString()).body());
var res = await client.PostAsJsonAsync("https://a.eztexting.com/v1/webhooks/subscriptions", new
{
    type = "inbound_text.received",
    callbackUrl = "https://api.example.com/webhooks/eztexting",
    secret = Environment.GetEnvironmentVariable("EZTEXTING_WEBHOOK_SECRET")
});
var sub = await res.Content.ReadFromJsonAsync<JsonElement>();
body, _ := json.Marshal(map[string]string{
	"type":        "inbound_text.received",
	"callbackUrl": "https://api.example.com/webhooks/eztexting",
	"secret":      os.Getenv("EZTEXTING_WEBHOOK_SECRET"),
})
req, _ := http.NewRequest("POST", "https://a.eztexting.com/v1/webhooks/subscriptions", bytes.NewReader(body))
req.SetBasicAuth(os.Getenv("EZTEXTING_USERNAME"), os.Getenv("EZTEXTING_PASSWORD"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
	panic(err)
}
defer resp.Body.Close()
var sub map[string]any
json.NewDecoder(resp.Body).Decode(&sub)
{
  "id": "9127"
}
FieldRequiredNotes
typeYesOne of the event types above.
callbackUrlYesMust be HTTPS and publicly reachable.
secretNo, but do itA random string (32+ characters) used to sign every callback. Generate it with your language's secure RNG; store it as a secret.
insecureSslNotrue allows a self-signed certificate on callbackUrl. Development only.

List, inspect, and delete subscriptions with GET /v1/webhooks/subscriptions, GET …/{id}, and DELETE …/{id}.


Payloads

inbound_text.received

{
  "id": "128461504003",
  "type": "inbound_text.received",
  "fromNumber": "15551234567",
  "toNumber": "18885550199",
  "message": "Hi, I never received my order",
  "received": "2026-11-05T19:02:11.408+00:00",
  "optIn": false,
  "optOut": false
}
FieldMeaning
idPresent when the text is a reply to a send from you in the last 12 hours: the message ID of that send. Otherwise the field is left out. It isn't unique: several replies to the same send carry the same id.
fromNumberThe contact's number (11 digits).
toNumberYour number that received it. Reply from this number.
messageThe text.
receivedISO 8601 UTC timestamp.
optIn / optOuttrue when this message was an opt-in or opt-out (for example, the contact texted STOP). When optOut is true, EZ Texting has already blocked future sends to this contact.

keyword.opt_in

{
  "id": "128461590003",
  "type": "keyword.opt_in",
  "fromNumber": "15551234567",
  "toNumber": "313131",
  "keyword": "JOIN",
  "received": "2026-11-05T19:04:37.902+00:00"
}

contact.created

Delivers the new contact's record: phoneNumber, firstName, lastName, email, source, optOut, createdAt, and groups. See the Contact object in the reference.


Verify the signature

When a subscription has a secret, every callback carries an X-Signature-256 header:

X-Signature-256: UMWapujybq8P7dnFCKhFweV2s8F7FyF6kvSOZLW2gYA=

It's computed as Base64( HMAC-SHA256( secret, raw request body ) ). The example above is the signature of the inbound_text.received payload shown earlier, exactly as shown, with the secret a-long-random-string. To verify:

  1. Read the raw request body as bytes, before any JSON parsing or re-serialization. Whitespace matters.
  2. Compute HMAC-SHA256 over those bytes with your secret as the key.
  3. Base64-encode the digest.
  4. Compare with the header using a constant-time comparison.
  5. Reject with 401 on mismatch.
import hmac, hashlib, base64, os
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["EZTEXTING_WEBHOOK_SECRET"].encode()

def valid_signature(raw_body: bytes, header: str) -> bool:
    expected = base64.b64encode(hmac.new(SECRET, raw_body, hashlib.sha256).digest()).decode()
    return hmac.compare_digest(expected, header or "")

@app.post("/webhooks/eztexting")
def eztexting_webhook():
    if not valid_signature(request.get_data(), request.headers.get("X-Signature-256")):
        abort(401)
    event = request.get_json()
    # do the real work asynchronously
    queue.enqueue(event)
    return "", 204
import express from "express";
import crypto from "node:crypto";

const app = express();
const SECRET = process.env.EZTEXTING_WEBHOOK_SECRET;

function validSignature(rawBody, header = "") {
  const expected = crypto.createHmac("sha256", SECRET).update(rawBody).digest("base64");
  return expected.length === header.length &&
         crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

// express.raw() keeps the body as bytes — do NOT use express.json() on this route
app.post("/webhooks/eztexting", express.raw({ type: "application/json" }), async (req, res) => {
  if (!validSignature(req.body, req.get("X-Signature-256"))) return res.sendStatus(401);
  const event = JSON.parse(req.body);
  // do the real work asynchronously
  await queue.enqueue(event);
  res.sendStatus(204);
});
<?php
$secret = getenv("EZTEXTING_WEBHOOK_SECRET");
$rawBody = file_get_contents("php://input");
$expected = base64_encode(hash_hmac("sha256", $rawBody, $secret, true));
$given = $_SERVER["HTTP_X_SIGNATURE_256"] ?? "";

if (!hash_equals($expected, $given)) {
    http_response_code(401);
    exit;
}

$event = json_decode($rawBody, true);
// do the real work asynchronously
$queue->enqueue($event);
http_response_code(204);
class EzTextingWebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token

  def create
    raw = request.raw_post
    expected = Base64.strict_encode64(OpenSSL::HMAC.digest("SHA256", ENV.fetch("EZTEXTING_WEBHOOK_SECRET"), raw))
    given = request.headers["X-Signature-256"].to_s
    return head :unauthorized unless ActiveSupport::SecurityUtils.secure_compare(expected, given)

    # do the real work asynchronously
    WebhookJob.perform_later(JSON.parse(raw))
    head :no_content
  end
end
@PostMapping("/webhooks/eztexting")
public ResponseEntity<Void> eztexting(@RequestBody byte[] rawBody,
                                      @RequestHeader(value = "X-Signature-256", required = false) String given) throws Exception {
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(System.getenv("EZTEXTING_WEBHOOK_SECRET").getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    String expected = Base64.getEncoder().encodeToString(mac.doFinal(rawBody));

    if (given == null || !MessageDigest.isEqual(expected.getBytes(StandardCharsets.UTF_8), given.getBytes(StandardCharsets.UTF_8))) {
        return ResponseEntity.status(401).build();
    }
    // do the real work asynchronously
    queue.enqueue(objectMapper.readTree(rawBody));
    return ResponseEntity.noContent().build();
}
app.MapPost("/webhooks/eztexting", async (HttpRequest req, IQueue queue) =>
{
    using var ms = new MemoryStream();
    await req.Body.CopyToAsync(ms);
    var rawBody = ms.ToArray();

    var key = Encoding.UTF8.GetBytes(Environment.GetEnvironmentVariable("EZTEXTING_WEBHOOK_SECRET")!);
    var expected = Convert.ToBase64String(HMACSHA256.HashData(key, rawBody));
    var given = req.Headers["X-Signature-256"].ToString();

    if (!CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(expected), Encoding.UTF8.GetBytes(given)))
        return Results.Unauthorized();

    // do the real work asynchronously
    await queue.EnqueueAsync(JsonDocument.Parse(rawBody));
    return Results.NoContent();
});
func eztextingWebhook(w http.ResponseWriter, r *http.Request) {
	rawBody, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
	if err != nil {
		http.Error(w, "bad body", http.StatusBadRequest)
		return
	}

	mac := hmac.New(sha256.New, []byte(os.Getenv("EZTEXTING_WEBHOOK_SECRET")))
	mac.Write(rawBody)
	expected := base64.StdEncoding.EncodeToString(mac.Sum(nil))

	if !hmac.Equal([]byte(expected), []byte(r.Header.Get("X-Signature-256"))) {
		http.Error(w, "invalid signature", http.StatusUnauthorized)
		return
	}

	var event map[string]any
	json.Unmarshal(rawBody, &event)
	// do the real work asynchronously
	queue.Enqueue(event)
	w.WriteHeader(http.StatusNoContent)
}

Test vector

Use this to check your implementation without sending a text:

Secreta-long-random-string
Body (exact bytes, no trailing newline){"id":"128461504003","type":"inbound_text.received","fromNumber":"15551234567","toNumber":"18885550199","message":"Thanks, got it!","received":"2026-11-05T18:26:42.117Z","optIn":false,"optOut":false}
Expected X-Signature-256mMwnBtaKRt9Ufa3/WSqCAsjqx84zdB1iS3aLou4Wqbg=
printf '%s' '{"id":"128461504003","type":"inbound_text.received","fromNumber":"15551234567","toNumber":"18885550199","message":"Thanks, got it!","received":"2026-11-05T18:26:42.117Z","optIn":false,"optOut":false}' \
  | openssl dgst -sha256 -hmac 'a-long-random-string' -binary | base64
# mMwnBtaKRt9Ufa3/WSqCAsjqx84zdB1iS3aLou4Wqbg=
Don't allowlist IPs instead

EZ Texting sends callbacks from cloud infrastructure whose addresses change without notice. Signature verification is the supported way to authenticate callbacks.


Designing a resilient handler

A resilient handler does four things, in this order:

  1. Verify the signature against the raw request bytes.
  2. Store the event durably (a database row or a queue message).
  3. Return 2xx. Only now. If you acknowledge before the event is stored and the process dies, the event is gone and EZ Texting believes you have it.
  4. Process asynchronously from what you stored.

Storing is cheap; it's what makes the handler fast and safe. Slow or failing handlers look like outages to the sender, so keep everything after step 3 out of the request path.

Expect to miss some. If your endpoint is down for a while, callbacks fail. After repeated failures EZ Texting may stop calling the subscription. If that happens, EZ Texting emails the account holder to let them know. Build a polling fallback (for inbound texts, a periodic sweep of GET /v1/conversations?filters[unread][eq]=true) as a safety net. Skip texts your webhook already stored. Two-way conversations has the code.

Monitor the subscription. After any outage, GET /v1/webhooks/subscriptions and confirm yours is still listed. If it isn't, re-create it and run the sweep.

Keep secrets per environment. Dev, staging, and production should each have their own subscription and secret. Delete dev subscriptions pointed at tunnel URLs when you're done.

Diagnose signature failures without logging payloads. Log the body length and a short hash of the raw bytes, the subscription ID, and the first few characters of the header you received, which is enough to tell "re-serialized by middleware" (length differs from what EZ Texting sent) from "wrong secret" (length matches, hash matches, signature doesn't). Never log the raw body, the secret, or full Authorization headers from your own API calls; inbound texts are customer data.


Testing locally

Expose a local port with a tunnel (ngrok http 3000), subscribe with the tunnel URL, and text your number. Full walkthrough in Testing your integration.


Related

API reference


Did this page help you?