WP_REST_Request::get_headers() : lire les en-têtes bruts d’une requête REST entrante

« Retrieves all headers from the request. » C’est en ces termes que la référence officielle décrit WP_REST_Request::get_headers(), sans préciser qu’un tout autre get_headers() existe déjà nativement en PHP, sans aucun rapport avec une requête REST en cours de traitement : celui-là sert à interroger les en-têtes de réponse d’une URL distante. Pour un endpoint qui doit vérifier un en-tête personnalisé posé par un front ou par un CDN en amont, c’est bien la méthode de la classe WP_REST_Request qu’il faut appeler, jamais la fonction globale du même nom.

Ce que retourne réellement la méthode

WP_REST_Request::get_headers() retourne un tableau associatif où chaque clé correspond à un nom d’en-tête, toujours en minuscules, quelle que soit la casse utilisée par le client qui a envoyé la requête. Un en-tête X-Front-Signature envoyé par un client sera donc retrouvé sous la clé x-front-signature dans ce tableau. Cette normalisation suit la pratique HTTP courante qui traite les noms d’en-têtes comme insensibles à la casse, mais elle surprend un développeur qui teste sa clé exacte telle qu’envoyée et obtient un tableau vide en retour.

add_action( 'rest_api_init', function () {
    register_rest_route( 'mon-domaine/v1', '/webhook', array(
        'methods'             => 'POST',
        'callback'            => 'mon_domaine_webhook_callback',
        'permission_callback' => '__return_true',
    ) );
} );

function mon_domaine_webhook_callback( WP_REST_Request $request ) {
    $headers = $request->get_headers();

    if ( empty( $headers['x-front-signature'] ) ) {
        return new WP_Error( 'signature_manquante', 'En-tête de signature absent.', array( 'status' => 401 ) );
    }

    return rest_ensure_response( array( 'recu' => true ) );
}

Une deuxième subtilité : les valeurs sont des tableaux

Chaque valeur du tableau retourné par get_headers() est elle-même un tableau, pas une chaîne directe. WordPress conserve cette structure pour gérer le cas, rare mais légal en HTTP, d’un même en-tête envoyé plusieurs fois dans la même requête. Accéder directement à $headers['x-front-signature'] donne donc un tableau à un ou plusieurs éléments, et non la valeur elle-même. C’est précisément pour éviter cette manipulation répétée que WordPress fournit une méthode dédiée à la lecture d’un en-tête unique :

$signature = $request->get_header( 'x-front-signature' );

if ( null === $signature ) {
    return new WP_Error( 'signature_manquante', 'En-tête de signature absent.', array( 'status' => 401 ) );
}

get_header() applique en interne la même normalisation de casse, récupère le tableau correspondant s’il existe, et retourne toutes ses valeurs jointes par une virgule sous forme de chaîne, ou null si l’en-tête est absent. Pour la très grande majorité des vérifications d’en-tête personnalisé, cette méthode évite d’avoir à retraiter la structure retournée par get_headers().

Pourquoi passer par get_headers() malgré tout

get_headers() reste utile quand un callback doit inspecter l’ensemble des en-têtes reçus plutôt qu’une clé précise, par exemple pour journaliser une requête entrante à des fins de diagnostic, ou pour détecter la présence d’un en-tête parmi plusieurs variantes possibles posées par différents CDN. Dans ce cas, itérer sur le tableau complet reste plus direct que d’appeler get_header() une fois par clé candidate :

foreach ( $request->get_headers() as $nom => $valeurs ) {
    if ( str_starts_with( $nom, 'cf-' ) ) {
        error_log( sprintf( 'En-tête Cloudflare reçu : %s = %s', $nom, implode( ', ', $valeurs ) ) );
    }
}

Un en-tête entrant n’a de valeur que si la normalisation appliquée par WordPress est comprise avant d’écrire la première condition qui le teste.

Le piège d’une confusion avec un en-tête de réponse

La confusion la plus fréquente vient du nom même de la méthode, proche de la fonction PHP native get_headers() qui sert à interroger une URL distante et n’a strictement rien à voir avec une requête REST entrante en cours de traitement. Une seconde confusion, plus discrète, consiste à mélanger la lecture des en-têtes entrants avec l’écriture des en-têtes de sortie sur l’objet WP_REST_Response, qui utilise ses propres méthodes (header(), get_headers() côté réponse cette fois) sur une classe distincte. Les deux classes portent des méthodes au nom identique mais opèrent sur des objets différents, l’un représentant ce qui a été reçu, l’autre ce qui s’apprête à être envoyé.

• Toujours normaliser en minuscules avant de comparer un nom d’en-tête
• Préférer get_header() pour une clé unique connue à l’avance
• Réserver get_headers() à une inspection d’ensemble ou une recherche par préfixe
• Ne jamais confondre cette lecture avec les en-têtes de la réponse renvoyée par le contrôleur

Conclusion

Lire un en-tête personnalisé posé par un front ou un CDN dans un contrôleur REST WordPress n’a rien à voir avec la fonction PHP globale du même nom : c’est WP_REST_Request::get_headers(), associée le plus souvent à get_header() pour une clé précise, qui donne accès à cette information, avec une normalisation systématique des noms en minuscules. Connaître cette normalisation avant d’écrire la première condition évite l’écueil classique d’un en-tête pourtant bien envoyé, mais jamais détecté côté serveur.

Correction du 11 octobre 2026 : get_header() ne renvoie pas la première valeur de l'en-tête mais toutes ses valeurs jointes par une virgule.