Hooks synchronisation, webhooks et contrôle d’accès

Ces hooks de HappenBoard Pro interviennent là où votre site échange avec d’autres systèmes, et à l’entrée de l’événement. Ils couvrent les webhooks sortants et Slack, la synchronisation des agendas Google et Outlook, le scanner de check-in et l’impression des badges.

La configuration des webhooks est décrite dans Les webhooks sortants. Celle du scanner est dans Le check-in par QR code. Si les hooks sont nouveaux pour vous, commencez par Étendre HappenBoard avec les hooks.

Vérifier la signature d’un webhook

Chaque envoi de webhook est un POST dont le corps JSON contient event, delivered_at, delivery_id et data. Il porte ces en-têtes :

• X-HappenBoard-Event : la clé de l’événement, par exemple rsvp.created.
• X-HappenBoard-Delivery : un identifiant qui reste le même à chaque nouvelle tentative d’un même envoi.
• X-HappenBoard-Timestamp : l’heure Unix de cette tentative.
• X-HappenBoard-Signature-V1 : t=<timestamp>,v1=<hex>, un HMAC-SHA256 de l’horodatage, d’un point et du corps brut, calculé avec le secret de signature du webhook.
• X-HappenBoard-Signature : sha256=<hex>, un HMAC du corps seul. Il reste envoyé pour les anciens destinataires, mais ne protège pas contre le rejeu.

Comparez la signature v1 en temps constant et refusez un horodatage éloigné de plus de cinq minutes de votre horloge. Modifier t casse la signature : une requête interceptée ne peut donc pas être rejouée plus tard.

// $secret est le secret de signature du webhook.
parse_str( str_replace( ',', '&', $_SERVER['HTTP_X_HAPPENBOARD_SIGNATURE_V1'] ?? '' ), $sig );
$t  = (string) ( $sig['t'] ?? '' );
$ok = ctype_digit( $t )
    && abs( time() - (int) $t ) <= 300
    && hash_equals( hash_hmac( 'sha256', $t . '.' . file_get_contents( 'php://input' ), $secret ), (string) ( $sig['v1'] ?? '' ) );

Calculez le HMAC sur le corps tel qu’il est arrivé, avant de décoder le JSON. Servez-vous ensuite de X-HappenBoard-Delivery pour ignorer un envoi déjà traité : chaque nouvelle tentative garde l’identifiant mais reçoit un nouvel horodatage.

Le secret de signature ne s’affiche qu’une fois : à la création du webhook, puis chaque fois que quelqu’un clique sur Generate a new secret dans son éditeur. Ensuite, la liste des webhooks n’en montre que les quatre derniers caractères. Côté REST, POST /happenboard/v1/pro/webhooks renvoie le nouveau secret une seule fois, et POST /happenboard/v1/pro/webhooks/{id}/secret le remplace.

Nouvelles tentatives et mise en pause

Les envois partent dans une tâche de fond, jamais dans la requête qui les a déclenchés. Un échec qui semble passager (aucune réponse, délai dépassé, HTTP 408, 429 ou 5xx) est retenté 1, 4, 16, 64 puis 256 minutes plus tard : six tentatives sur environ six heures. Les nouvelles tentatives passent par Action Scheduler s’il est installé, par WP-Cron sinon. Toute autre réponse est définitive, et les redirections ne sont jamais suivies.

Chaque tentative ratée ajoute un au compteur d’échecs consécutifs du webhook, et une réponse 2xx le remet à zéro. À 50, Pro désactive le webhook, ses tentatives en attente s’arrêtent, la liste l’affiche comme Paused et l’administrateur du site reçoit un e-mail. Un webhook qui avait déjà dépassé la limite est désactivé dès que la carte Webhooks en affiche la liste. Le réactiver remet le compteur à zéro.

Le bouton Test envoie tout de suite un événement webhook.test. Il déclenche les hooks d’envoi comme une vraie tentative, mais n’est jamais retenté ni compté.

Le check-in à l’entrée

• Chaque scan appelle POST /happenboard/v1/pro/checkin/mark avec le code du billet, et l’événement choisi dans Event at this door s’il y en a un.
• Un code de billet qui échoue à la vérification reçoit une erreur HTTP 400 et compte pour le blocage (happenboard_pro_checkin_lockout).
• Un billet authentique est refusé avec une erreur HTTP 409 s’il est pour un autre événement, si sa réservation ne détient aucune place, ou s’il est pour une autre date d’un événement récurrent. Cela déclenche happenboard_pro_attendee_checkin_refused.
• Un scan accepté déclenche happenboard_pro_attendee_checked_in, documenté avec les hooks participants.
• Le bouton Undo du scanner supprime ce check-in et déclenche happenboard_pro_attendee_checkin_undone.

Les filtres qui façonnent l’événement envoyé à Google et Outlook sont documentés avec les hooks événements.

do_action( 'happenboard_pro_webhook_delivered', array $webhook, string $event, array $data, int $status, string $body )

add_action(
    'happenboard_pro_webhook_delivered',
    function ( $webhook, $event, $data, $status, $body ) {
        if ( $status >= 200 && $status < 300 ) {
            return; // Envoi réussi.
        }
        // Ce hook se déclenche aussi pour les réponses 3xx, 4xx et 5xx.
        error_log( sprintf(
            'Webhook %s to %s answered HTTP %d: %s',
            $event,
            (string) ( $webhook['url'] ?? '' ),
            $status,
            substr( $body, 0, 200 )
        ) );
    },
    10,
    5
);

do_action( 'happenboard_pro_webhook_failed', array $webhook, string $event, array $data, string $error )

add_action(
    'happenboard_pro_webhook_failed',
    function ( $webhook, $event, $data, $error ) {
        // Pro retente seul : une seule alerte, au troisième échec d'affilée.
        $failures = (int) ( $webhook['lastResult']['failures'] ?? 0 ) + 1;
        if ( 3 !== $failures ) {
            return;
        }
        wp_mail(
            get_option( 'admin_email' ),
            'Webhook unreachable',
            sprintf( '%s (%s): %s', (string) ( $webhook['url'] ?? '' ), $event, $error )
        );
    },
    10,
    4
);

apply_filters( 'happenboard_pro_webhook_auto_pause_after', int $attempts )

add_filter(
    'happenboard_pro_webhook_auto_pause_after',
    function ( $attempts ) {
        // Notre CRM a de longues maintenances : laissons-lui plus de marge.
        return 200;
    }
);

do_action( 'happenboard_pro_webhook_auto_paused', int $webhook_id, int $failures )

add_action(
    'happenboard_pro_webhook_auto_paused',
    function ( $webhook_id, $failures ) {
        // Pro prévient déjà l’administrateur du site : prévenez aussi le développeur.
        wp_mail(
            '[email protected]',
            'Webhook désactivé',
            sprintf(
                'Le webhook #%d a échoué %d fois de suite et a été désactivé. Réparez le destinataire, puis réactivez-le dans HappenBoard > Integrations > Webhooks (Pro).',
                $webhook_id,
                $failures
            )
        );
    },
    10,
    2
);

apply_filters( 'happenboard_pro_slack_webhook_url_valid', bool $valid, string $url )

add_filter(
    'happenboard_pro_slack_webhook_url_valid',
    function ( $valid, $url ) {
        // Accepter aussi nos webhooks entrants Mattermost.
        return $valid || str_starts_with( $url, 'https://chat.example.org/hooks/' );
    },
    10,
    2
);

do_action( 'happenboard_pro_attendee_checkin_refused', int $attendee_id, int $event_id, string $status, int $seat_index, string $source, string $reason, int $scanned_for )

add_action(
    'happenboard_pro_attendee_checkin_refused',
    function ( $attendee_id, $event_id, $status, $seat_index, $source, $reason, $scanned_for ) {
        if ( 'wrong_event' !== $reason ) {
            return;
        }
        error_log( sprintf(
            'Ticket of attendee %d (event %d) was scanned at the door of event %d.',
            $attendee_id,
            $event_id,
            $scanned_for
        ) );
    },
    10,
    7
);

do_action( 'happenboard_pro_attendee_checkin_undone', int $checkin_id, int $attendee_id, int $event_id, int $seat_index )

add_action(
    'happenboard_pro_attendee_checkin_undone',
    function ( $checkin_id, $attendee_id, $event_id, $seat_index ) {
        // Retirer l'entrée que notre compteur de porte avait ajoutée au check-in.
        $count = (int) get_post_meta( $event_id, 'my_door_count', true );
        update_post_meta( $event_id, 'my_door_count', max( 0, $count - 1 ) );
    },
    10,
    4
);

do_action( 'happenboard_pro_checkin_lockout', int $actor_id, int $count )

add_action(
    'happenboard_pro_checkin_lockout',
    function ( $actor_id, $count ) {
        $user = get_userdata( (int) $actor_id );
        wp_mail(
            get_option( 'admin_email' ),
            'Scanner de check-in bloqué',
            sprintf(
                '%s est bloqué au check-in pendant 5 minutes après %d codes invalides.',
                $user ? $user->display_name : 'Un utilisateur inconnu',
                $count
            )
        );
    },
    10,
    2
);

apply_filters( 'happenboard_badges_per_sheet', int $per_sheet )

add_filter(
    'happenboard_badges_per_sheet',
    function ( $per_sheet ) {
        // Serveur généreux : moins de fichiers PDF, plus gros.
        return 300;
    }
);

do_action( 'happenboard_pro_calendar_event_pushed', int $post_id, string $provider, array $response )

add_action(
    'happenboard_pro_calendar_event_pushed',
    function ( $post_id, $provider, $response ) {
        if ( 'google' !== $provider ) {
            return; // Se déclenche aussi avec 'outlook'.
        }
        update_post_meta(
            (int) $post_id,
            'my_gcal_html_link',
            (string) ( $response['htmlLink'] ?? '' )
        );
    },
    10,
    3
);

apply_filters( 'happenboard_pro_gcal_exdates', array $exdates, int $event_id )

add_filter(
    'happenboard_pro_gcal_exdates',
    function ( $exdates, $event_id ) {
        // Les dates retirées sont déjà dans la liste. Gardez aussi nos dates réservées
        // aux membres hors de Google, enregistrées en débuts UTC comme 2026-11-02T18:00:00Z.
        $private = get_post_meta( $event_id, 'my_private_dates', true );
        if ( is_array( $private ) ) {
            $exdates = array_merge( $exdates, $private );
        }
        return $exdates;
    },
    10,
    2
);

do_action( 'happenboard_pro_calendar_local_wins', int $post_id )

add_action(
    'happenboard_pro_calendar_local_wins',
    function ( $post_id ) {
        // Trace seulement : Pro renvoie déjà cet événement vers Google.
        error_log( sprintf(
            'Google conflict on event %d, WordPress copy kept.',
            (int) $post_id
        ) );
    }
);

do_action( 'happenboard_pro_calendar_local_wins_outlook', int $post_id )

add_action(
    'happenboard_pro_calendar_local_wins_outlook',
    function ( $post_id ) {
        // Trace seulement : Pro renvoie déjà cet événement vers Outlook.
        error_log( sprintf(
            'Outlook conflict on event %d, WordPress copy kept.',
            (int) $post_id
        ) );
    }
);

apply_filters( 'happenboard_pro_host_busy_unknown_blocks', bool $blocks, array $hosts )

add_filter(
    'happenboard_pro_host_busy_unknown_blocks',
    function ( $blocks, $hosts ) {
        // Toujours proposer le compte de l'accueil (utilisateur 12), même si
        // son agenda est illisible ; les autres hôtes restent bloqués.
        return array( 12 ) === array_values( $hosts ) ? false : $blocks;
    },
    10,
    2
);

Pour aller plus loin

• Les webhooks sortants : comment le propriétaire du site ajoute un webhook et choisit ses événements.
• Notifications Slack : la carte Slack à laquelle s’applique le filtre d’URL.
• Hooks participants et inscriptions : l’action de check-in et les autres événements participants sur lesquels reposent les webhooks.