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 type | Fires when | Payload |
|---|---|---|
inbound_text.received | A contact texts one of your numbers. Includes replies, STOP/HELP, keyword texts, and MMS. | Message |
keyword.opt_in | A contact texts one of your keywords and is opted in. | Keyword opt-in |
contact.created | A 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"
}| Field | Required | Notes |
|---|---|---|
type | Yes | One of the event types above. |
callbackUrl | Yes | Must be HTTPS and publicly reachable. |
secret | No, but do it | A random string (32+ characters) used to sign every callback. Generate it with your language's secure RNG; store it as a secret. |
insecureSsl | No | true 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
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
}| Field | Meaning |
|---|---|
id | Present 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. |
fromNumber | The contact's number (11 digits). |
toNumber | Your number that received it. Reply from this number. |
message | The text. |
received | ISO 8601 UTC timestamp. |
optIn / optOut | true 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
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
contact.createdDelivers 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:
- Read the raw request body as bytes, before any JSON parsing or re-serialization. Whitespace matters.
- Compute HMAC-SHA256 over those bytes with your secret as the key.
- Base64-encode the digest.
- Compare with the header using a constant-time comparison.
- Reject with
401on 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 "", 204import 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:
| Secret | a-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-256 | mMwnBtaKRt9Ufa3/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=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:
- Verify the signature against the raw request bytes.
- Store the event durably (a database row or a queue message).
- 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. - 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
POST /v1/webhooks/subscriptionsGET /v1/webhooks/subscriptionsGET /v1/webhooks/subscriptions/{id}DELETE /v1/webhooks/subscriptions/{id}
Try Troubleshooting, check status.eztexting.com, or contact support.
Updated 2 days ago