Envoyer un SMS en Go : net/http, contexte et webhooks

func doitLire(nom string) string {
	v, ok := os.LookupEnv(nom)
	if !ok || v == "" {
		log.Fatalf("variable d'environnement %s absente", nom)
	}
	return v
}

appID := doitLire("CONEXTEO_APP_ID")
cle := doitLire("CONEXTEO_API_KEY")

Premier piège : intervertir les deux valeurs. L'API répond alors 401 Unauthorized — exactement le même code que si la clé était fausse ou révoquée. On en régénère une, et le problème persiste. Le moyen mnémotechnique : APP identifie l'application, KEY est le secret. Avec des identifiants fraîchement copiés, échangez les deux en-têtes avant toute autre hypothèse.

Second piège, propre à Go : os.Getenv renvoie une chaîne vide, sans erreur, quand la variable n'existe pas. Un conteneur lancé sans son fichier d'environnement envoie donc des en-têtes vides et reçoit un 401 qui ressemble à un problème de clé. os.LookupEnv et un arrêt immédiat transforment ce 401 mystérieux en un message explicite dans les journaux de démarrage.

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
	"time"
)

func main() {
	corps, _ := json.Marshal(map[string]any{
		"content":    "Votre code de connexion : 847291",
		"sender":     "MaBoutique",
		"recipients": []string{"+33612345678"},
	})

	req, _ := http.NewRequest(http.MethodPost,
		"https://api.conexteo.com/messages/sms", bytes.NewReader(corps))
	req.Header.Set("X-APP-ID", os.Getenv("CONEXTEO_APP_ID"))
	req.Header.Set("X-API-KEY", os.Getenv("CONEXTEO_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{Timeout: 10 * time.Second}
	res, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	reponse, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode, string(reponse))
	// 200 {"success":true,"message":"message created",
	//      "message_id":123456,"credits_used":1}
}

Pas de http.Post, pas de http.DefaultClient. Le client par défaut n'a aucun délai d’expiration : une requête qui ne revient pas immobilise la goroutine indéfiniment. Sur un service qui envoie des milliers de messages, ce sont autant de goroutines et de connexions qui s'accumulent sans bruit. Créez votre propre http.Client avec un Timeout, une fois pour toutes.

Le Content-Type n’est pas posé pour vous. Avec http.NewRequest, c'est à vous de l'ajouter. Sans lui, le corps JSON n'est pas interprété et l'API répond 400.

// ✗ Ce code considère un 400 comme un succès
res, err := client.Do(req)
if err != nil {
	return err // n'arrive qu'en cas de panne réseau ou d'expiration
}
defer res.Body.Close()
var r Reponse
json.NewDecoder(res.Body).Decode(&r)
return nil // r.MessageID vaut 0, et personne n'est prévenu

// ✓ Le code HTTP se teste explicitement
if res.StatusCode != http.StatusOK {
	corps, _ := io.ReadAll(res.Body)
	return fmt.Errorf("conexteo %d : %s", res.StatusCode, corps)
}

La signature de ce bug en production : des envois qui « réussissent » dans vos journaux, un message_id à zéro en base — la valeur nulle d'un int64 —, et des clients qui n'ont rien reçu. Aucune alerte ne se déclenche, puisqu'aucune erreur n'a été renvoyée.

Et fermez toujours le corps. Un res.Body jamais fermé, même sur une réponse d'erreur, empêche le transport de réutiliser la connexion. Le service fonctionne en recette, puis ouvre une nouvelle connexion TLS à chaque envoi en production, jusqu'à épuiser les descripteurs de fichiers. Lisez le corps en entier, puis fermez-le, sur tous les chemins.

// Package conexteo : client minimal de l'API SMS et RCS.
package conexteo

import (
	"bytes"
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"net/http"
	"time"
)

const baseURL = "https://api.conexteo.com"

type Client struct {
	appID, cle string
	http       *http.Client
}

func Nouveau(appID, cle string) *Client {
	return &Client{appID: appID, cle: cle,
		http: &http.Client{Timeout: 10 * time.Second}}
}

type Erreur struct {
	Statut int
	Corps  string
}

func (e *Erreur) Error() string {
	return fmt.Sprintf("conexteo %d : %s", e.Statut, e.Corps)
}

// ErrDejaEnvoye signale un 409 : le message a déjà été accepté.
var ErrDejaEnvoye = errors.New("conexteo : external_id déjà traité")

func (c *Client) appeler(ctx context.Context, chemin string, charge, sortie any) error {
	corps, err := json.Marshal(charge)
	if err != nil {
		return err
	}
	const essais = 3
	for essai := 0; ; essai++ {
		req, err := http.NewRequestWithContext(ctx, http.MethodPost,
			baseURL+chemin, bytes.NewReader(corps))
		if err != nil {
			return err
		}
		req.Header.Set("X-APP-ID", c.appID)
		req.Header.Set("X-API-KEY", c.cle)
		req.Header.Set("Content-Type", "application/json")

		res, err := c.http.Do(req)
		if err != nil {
			// Panne réseau ou expiration : on rejoue, sauf si
			// l'appelant a lui-même annulé.
			if ctx.Err() == nil && essai < essais-1 && attendre(ctx, essai) == nil {
				continue
			}
			return err
		}
		donnees, _ := io.ReadAll(res.Body)
		res.Body.Close()

		switch {
		case res.StatusCode == http.StatusConflict:
			return ErrDejaEnvoye
		case res.StatusCode >= 500 && essai < essais-1:
			if err := attendre(ctx, essai); err != nil {
				return err
			}
			continue
		case res.StatusCode != http.StatusOK:
			return &Erreur{Statut: res.StatusCode, Corps: string(donnees)}
		}
		if sortie == nil {
			return nil
		}
		return json.Unmarshal(donnees, sortie)
	}
}

// attendre double le délai à chaque essai, et s'interrompt
// si le contexte est annulé pendant la pause.
func attendre(ctx context.Context, essai int) error {
	select {
	case <-time.After(time.Duration(1<<essai) * 500 * time.Millisecond):
		return nil
	case <-ctx.Done():
		return ctx.Err()
	}
}

Ne rejouez jamais un 4xx. Un 400 rejoué trois fois reste un 400. Seules les erreurs serveur et les pannes réseau méritent une reprise, avec un délai qui double à chaque essai. Et la pause elle-même écoute ctx.Done() : un time.Sleep à cet endroit ferait attendre un appelant qui a déjà abandonné.

Un seul client pour tout le programme. Un *http.Client est sûr en accès concurrent et garde ses connexions ouvertes. En créer un par envoi, c'est refaire une poignée de main TLS à chaque message.

type SMS struct {
	Content    string     `json:"content"`
	Recipients []string   `json:"recipients"`
	Sender     string     `json:"sender,omitempty"`
	ExternalID string     `json:"external_id,omitempty"`
	ScheduleAt *time.Time `json:"scheduleAt,omitempty"`
}

type Reponse struct {
	MessageID   int64 `json:"message_id"`
	CreditsUsed int   `json:"credits_used"`
}

func (c *Client) EnvoyerSMS(ctx context.Context, m SMS) (Reponse, error) {
	var r Reponse
	err := c.appeler(ctx, "/messages/sms", m, &r)
	return r, err
}

// Côté appelant
_, err := client.EnvoyerSMS(ctx, conexteo.SMS{
	Content:    "Votre commande " + cmd.Reference + " est expédiée.",
	Sender:     "MaBoutique",
	Recipients: []string{cmd.Mobile},
	ExternalID: "expedition-" + cmd.ID, // déterministe
})
if err != nil && !errors.Is(err, conexteo.ErrDejaEnvoye) {
	return err
}

// ✗ Le contexte de la requête meurt quand le handler retourne
func creerCommande(w http.ResponseWriter, r *http.Request) {
	cmd := enregistrer(r)
	go client.EnvoyerSMS(r.Context(), smsConfirmation(cmd))
	w.WriteHeader(http.StatusCreated) // ← r.Context() est annulé ici
}

// ✓ Une file en mémoire, vidée par un travailleur au long cours
var envois = make(chan conexteo.SMS, 1000)

func travailleur(client *conexteo.Client) {
	for m := range envois {
		ctx, annuler := context.WithTimeout(context.Background(), 30*time.Second)
		_, err := client.EnvoyerSMS(ctx, m)
		annuler()
		if err != nil && !errors.Is(err, conexteo.ErrDejaEnvoye) {
			log.Printf("envoi %s : %v", m.ExternalID, err)
		}
	}
}

func creerCommande(w http.ResponseWriter, r *http.Request) {
	cmd := enregistrer(r)
	w.WriteHeader(http.StatusCreated)  // on répond d'abord
	envois <- smsConfirmation(cmd)     // puis on empile
}

Pourquoi le bug est intermittent. Le contexte d'une requête entrante est annulé dès que le handler a répondu. Si la goroutine a déjà émis sa requête, l'envoi aboutit parfois ; si elle était encore en train de se connecter, il échoue. En recette, sur une machine rapide, presque tout passe. En production, une part des messages disparaît.

Si vous tenez à garder les valeurs du contexte — identifiant de trace, utilisateur —, context.WithoutCancel(r.Context()), disponible depuis Go 1.21, conserve les valeurs sans hériter de l'annulation. Ajoutez-lui un délai propre. Pour des volumes réels, ou si un redémarrage ne doit perdre aucun message, remplacez le canal par une file persistante : base de données, Redis, ou le gestionnaire de tâches que votre équipe utilise déjà.

// ✗ La valeur zéro est sérialisée, pas omise
ScheduleAt time.Time `json:"scheduleAt,omitempty"`
// → "scheduleAt":"0001-01-01T00:00:00Z" sur chaque envoi immédiat

// ✓ Un pointeur, nil quand il n'y a pas de programmation
ScheduleAt *time.Time `json:"scheduleAt,omitempty"`

// ✓ Ou, depuis Go 1.24, l'option omitzero
ScheduleAt time.Time `json:"scheduleAt,omitzero"`

import _ "time/tzdata" // embarque la base des fuseaux dans le binaire

paris, err := time.LoadLocation("Europe/Paris")
if err != nil {
	return err
}
quand := time.Date(2026, time.November, 3, 9, 0, 0, 0, paris).UTC()

_, err = client.EnvoyerSMS(ctx, conexteo.SMS{
	Content:    "Votre rendez-vous est demain à 14h.",
	Sender:     "Cabinet",
	Recipients: []string{"+33612345678"},
	ScheduleAt: &quand, // "2026-11-03T08:00:00Z"
})

L’import de time/tzdata n’est pas décoratif. Une image Docker construite FROM scratch ou sur une base minimale ne contient pas la base des fuseaux horaires. time.LoadLocation("Europe/Paris") renvoie alors une erreur — ou, si elle est ignorée, une location vide, et vos rappels partent une à deux heures trop tôt selon la saison. Cet import ajoute quelques centaines de kilo-octets au binaire et supprime le problème.

package conexteo

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"errors"
	"io"
	"net/http"
	"strconv"
	"strings"
	"time"
)

var ErrSignature = errors.New("signature de webhook invalide")

// VerifierWebhook lit le corps brut, contrôle la signature et
// renvoie le corps pour qu'il soit décodé ensuite.
func VerifierWebhook(r *http.Request, secret string) ([]byte, error) {
	corps, err := io.ReadAll(http.MaxBytesReader(nil, r.Body, 1<<20))
	if err != nil {
		return nil, err
	}

	horodatage := r.Header.Get("X-Conexteo-Timestamp")
	secondes, err := strconv.ParseInt(horodatage, 10, 64)
	if err != nil {
		return nil, ErrSignature
	}
	if d := time.Since(time.Unix(secondes, 0)); d > 5*time.Minute || d < -5*time.Minute {
		return nil, ErrSignature // trop ancien : rejeu possible
	}

	recue, ok := strings.CutPrefix(r.Header.Get("X-Conexteo-Signature"), "v1=")
	if !ok {
		return nil, ErrSignature
	}

	mac := hmac.New(sha256.New, []byte(secret)) // whsec_…
	mac.Write([]byte(horodatage + "."))
	mac.Write(corps) // les octets reçus, jamais une re-sérialisation
	attendue := hex.EncodeToString(mac.Sum(nil))

	if !hmac.Equal([]byte(recue), []byte(attendue)) {
		return nil, ErrSignature
	}
	return corps, nil
}

// Dans le service
func webhook(w http.ResponseWriter, r *http.Request) {
	corps, err := conexteo.VerifierWebhook(r, secret)
	if err != nil {
		http.Error(w, "signature invalide", http.StatusUnauthorized)
		return
	}
	id := r.Header.Get("X-Conexteo-Webhook-Id")
	if dejaTraite(id) {
		w.WriteHeader(http.StatusNoContent) // rejeu : déjà pris en compte
		return
	}
	evenements <- corps                 // traitement hors de la requête
	w.WriteHeader(http.StatusNoContent) // tout 2xx vaut accusé de réception
}

Ne décodez rien avant de vérifier. Un json.NewDecoder(r.Body) placé avant la vérification consomme le flux : il ne reste plus rien à signer. Sous Gin, c.ShouldBindJSON fait la même chose ; lisez le corps avec c.GetRawData(), vérifiez, puis décodez avec json.Unmarshal. Et ne recalculez jamais la signature sur une structure re-sérialisée : l'ordre des champs et les espaces ne correspondront pas à l'original.

Comparez avec hmac.Equal, pas avec ==. La première compare en temps constant, la seconde laisse fuiter la position du premier caractère différent. Et rejetez les horodatages de plus de cinq minutes : c'est ce qui empêche de rejouer une requête interceptée.

Répondez vite. Toute réponse 2xx vaut accusé de réception ; un autre code, un délai dépassé ou une erreur réseau comptent comme un échec et déclenchent un nouvel essai. Un handler qui attend la fin d'un traitement long reçoit le même événement encore et encore.

type Bouton struct {
	Type  string `json:"type"`
	Title string `json:"title"`
	URL   string `json:"url,omitempty"`
}

type Carte struct {
	Title       string   `json:"title"`
	Description string   `json:"description"`
	Media       string   `json:"media,omitempty"`
	Buttons     []Bouton `json:"buttons,omitempty"`
}

type Repli struct {
	Content string `json:"content"`
	Sender  string `json:"sender,omitempty"`
}

type Contact struct {
	Recipient string `json:"recipient"`
}

type RCS struct {
	Type     string    `json:"type"`
	Data     any       `json:"data"`
	Fallback Repli     `json:"fallback"` // SMS envoyé si le mobile ne gère pas le RCS
	Contacts []Contact `json:"contacts"`
}

type ReponseRCS struct {
	RCS struct {
		Sent int `json:"sent"`
	} `json:"rcs"`
	SMS struct {
		Sent int `json:"sent"`
	} `json:"sms"`
}

func (c *Client) EnvoyerRCS(ctx context.Context, m RCS) (ReponseRCS, error) {
	var r ReponseRCS
	err := c.appeler(ctx, "/messages/rcs", m, &r)
	return r, err
}

r, err := client.EnvoyerRCS(ctx, conexteo.RCS{
	Type: "card",
	Data: conexteo.Carte{
		Title:       "Votre commande est prête",
		Description: "Retrait en boutique jusqu'à samedi 19h.",
		Media:       "https://exemple.fr/colis.jpg", // PNG ou JPG, jamais WebP
		Buttons:     []conexteo.Bouton{{Type: "url", Title: "Suivre", URL: "https://…"}},
	},
	Fallback: conexteo.Repli{Content: "Votre commande est prête. Retrait jusqu'à samedi 19h.", Sender: "MaBoutique"},
	Contacts: []conexteo.Contact{{Recipient: "+33612345678"}},
})
// r.RCS.Sent = 412, r.SMS.Sent = 88
//   → 82 % de votre base a reçu la version enrichie.

Le champ s’appelle contacts, pas recipients. C'est la première erreur quand on recopie le code SMS. Avec des structures typées, elle se voit à la relecture ; avec une map, elle se découvre au premier 400.

Les deux compteurs de la réponse sont la mesure la plus utile de toute l’API : ils donnent le taux de compatibilité RCS réel de votre base, campagne après campagne. Aucune statistique de marché ne remplace ce chiffre.

Votre premier SMS en Go dans dix minutes

L'inscription est gratuite et sans carte bancaire, avec cinq SMS de test pour vérifier le rendu réel sur mobile. Vos identifiants d'API sont disponibles immédiatement dans Mon Compte / API / Webhook.