Testing your integration

How to test your integration safely.

Use your own numbers

The simplest, safest test harness is a phone (or a few) that you control.

  • Send single tests to yourself. Most transactional sends (a reminder, a passcode, an order update) go to one number. Point toNumbers at your own phone while you develop.
  • Create a test group (for example, API Test) containing only your team's numbers. Point every campaign-style test at that groupId. You can't accidentally blast customers from a group that doesn't contain any.
  • Keep test contacts obviously named (firstName: "TEST") so they're easy to find and exclude: GET /v1/contacts?filters[firstName][like]=TEST.
  • Put the environment in the message during development: [DEV] Your code is 123456.

Test without delivering

Several calls are useful for exercising your code paths without actually sending:

Want to test…Do this
AuthenticationGET /v1/credits: cheap, read-only, and fails with 401 if your credentials are wrong.
Request validationSend to a deliberately bad number. strictValidation is on by default, so you get the 400 and nothing goes out.
Scheduling logicSend with a sendAt an hour from now, confirm it appears in GET /v1/campaign-info, then cancel it with DELETE /v1/messages ({"ids": ["<id>"]}). No message, no credits.
TemplatesPOST /v1/message-templates and GET /v1/message-templates/{id} are free. Verify the variable names before you send with one.
Contact syncPOST /v1/contacts/batch then GET /v1/contacts/{phoneNumber}. The requests are free, but they can trigger a Workflow that sends a text (see below).
Reporting codeUse the message ID from any earlier real send; reports are read-only.
Contact sync can trigger a Workflow

Use a test contact and a group you control. Before updating group membership or a date field, check whether an active Workflow uses it. Your sync can trigger a message even if your code never calls POST /v1/messages. See Automation workflows.


Testing webhooks locally

Webhook callbacks need a public HTTPS URL, which your laptop doesn't have. A tunnelling tool gives you one for the duration of a dev session:

  1. Start your webhook handler locally, for example on port 3000.
  2. Run a tunnel (ngrok http 3000, or Cloudflare Tunnel, localtunnel, etc.) and copy the https://… URL it prints.
  3. Create a subscription pointing at it:
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://a1b2c3d4.ngrok.app/webhooks/eztexting",
    "secret": "dev-secret"
  }'
import os, requests

auth = (os.environ["EZTEXTING_USERNAME"], os.environ["EZTEXTING_PASSWORD"])
sub = requests.post(
    "https://a.eztexting.com/v1/webhooks/subscriptions",
    auth=auth,
    json={
        "type": "inbound_text.received",
        "callbackUrl": "https://a1b2c3d4.ngrok.app/webhooks/eztexting",
        "secret": "dev-secret",
    },
    timeout=30,
).json()
# keep it so you can delete the subscription later
print(sub["id"])
const credentials = Buffer.from(
  `${process.env.EZTEXTING_USERNAME}:${process.env.EZTEXTING_PASSWORD}`
).toString("base64");

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://a1b2c3d4.ngrok.app/webhooks/eztexting",
    secret: "dev-secret",
  }),
})).json();
// keep it so you can delete the subscription later
console.log(sub.id);
<?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://a1b2c3d4.ngrok.app/webhooks/eztexting",
        "secret" => "dev-secret",
    ]),
]);
$sub = json_decode(curl_exec($ch), true);
curl_close($ch);
// keep it so you can delete the subscription later
echo $sub['id'], "\n";
require "net/http"
require "json"

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://a1b2c3d4.ngrok.app/webhooks/eztexting",
  secret: "dev-secret"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
# keep it so you can delete the subscription later
puts JSON.parse(res.body)["id"]
String basicAuth = Base64.getEncoder().encodeToString(
    (System.getenv("EZTEXTING_USERNAME") + ":" + System.getenv("EZTEXTING_PASSWORD")).getBytes());

String json = """
    {
      "type": "inbound_text.received",
      "callbackUrl": "https://a1b2c3d4.ngrok.app/webhooks/eztexting",
      "secret": "dev-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();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
// keep the id so you can delete the subscription later
System.out.println(response.body());
var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes(
    $"{Environment.GetEnvironmentVariable("EZTEXTING_USERNAME")}:{Environment.GetEnvironmentVariable("EZTEXTING_PASSWORD")}"));
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);

var res = await client.PostAsJsonAsync("https://a.eztexting.com/v1/webhooks/subscriptions", new
{
    type = "inbound_text.received",
    callbackUrl = "https://a1b2c3d4.ngrok.app/webhooks/eztexting",
    secret = "dev-secret"
});
var sub = await res.Content.ReadFromJsonAsync<JsonElement>();
// keep it so you can delete the subscription later
Console.WriteLine(sub.GetProperty("id"));
body, _ := json.Marshal(map[string]string{
	"type":        "inbound_text.received",
	"callbackUrl": "https://a1b2c3d4.ngrok.app/webhooks/eztexting",
	"secret":      "dev-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 struct{ ID string `json:"id"` }
json.NewDecoder(resp.Body).Decode(&sub)
// keep it so you can delete the subscription later
fmt.Println(sub.ID)
  1. Text your EZ Texting number from your phone. The payload should hit your handler within seconds.
  2. Delete the subscription when you're done (DELETE /v1/webhooks/subscriptions/{id}). Tunnel URLs are ephemeral; a dead callback URL will accumulate failures.

Keep your dev and production subscriptions separate. They're independent objects with independent secrets. List what's registered with GET /v1/webhooks/subscriptions whenever something looks off.


Pre-launch checklist

Before pointing production traffic at the API:

  • Credentials come from environment variables or a secrets manager, never source control.
  • If you use OAuth 2.0 tokens, refresh is handled before the 90-minute expiry. → Authentication
  • Every number is normalized to 11 digits at the edge. → Phone number formatting
  • Nothing sets strictValidation: false unless skipping bad numbers is intended.
  • 429 responses are retried after the X-Rate-Limit-Retry-After-Milliseconds delay, with a cap. → Rate limits
  • Reads and other idempotent operations are retried with backoff. If POST /v1/messages times out or returns 5xx, the code checks whether the send was accepted before submitting it again. → Idempotency & retries
  • Webhook handlers verify X-Signature-256, respond 2xx fast, and tolerate duplicate deliveries. → Webhooks
  • Something polls GET /v1/credits and alerts before the balance hits zero.
  • Opt-in is captured and recorded, and your messages include your business name (in the text or with companyName) and opt-out language such as "Reply STOP to opt out". → Compliance
  • You've sent a real message to a real phone from the production environment and seen it in the delivery report.

Related


Did this page help you?