Calendar sync, webhook and check-in hooks

These HappenBoard Pro hooks run where your site talks to other systems, and at the door. They cover outgoing webhooks and Slack, the Google and Outlook calendar sync, the check-in scanner and badge printing.

The setup side is in Outbound webhooks and QR code check-in. If you are new to hooks, start with Extending HappenBoard with hooks.

Verifying a webhook signature

Every webhook delivery is a POST with a JSON body holding event, delivered_at, delivery_id and data. It carries these headers:

• X-HappenBoard-Event: the event key, such as rsvp.created.
• X-HappenBoard-Delivery: an ID that stays the same on every retry of one delivery.
• X-HappenBoard-Timestamp: the Unix time of this attempt.
• X-HappenBoard-Signature-V1: t=<timestamp>,v1=<hex>, an HMAC-SHA256 of the timestamp, a dot and the raw body, keyed with the webhook’s signing secret.
• X-HappenBoard-Signature: sha256=<hex>, an HMAC of the body alone. It is still sent for older receivers but gives no protection against replays.

Check the v1 signature in constant time, and refuse a timestamp more than five minutes from your clock. Changing t breaks the signature, so a captured request cannot be replayed later.

// $secret is the webhook's signing secret.
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'] ?? '' ) );

Hash the body exactly as it arrived, before decoding the JSON. Then use X-HappenBoard-Delivery to ignore a delivery you already processed: each retry keeps the ID but gets a fresh timestamp.

The signing secret is shown once: when the webhook is created, and each time someone clicks Generate a new secret in its editor. After that, the webhook list only shows its last four characters. Over REST, POST /happenboard/v1/pro/webhooks answers the new secret once, and POST /happenboard/v1/pro/webhooks/{id}/secret replaces it.

How deliveries are retried and paused

Deliveries leave in a background job, never in the request that triggered them. A failure that looks temporary (no response, a timeout, HTTP 408, 429 or 5xx) is retried 1, 4, 16, 64 and 256 minutes later: six attempts over about six hours. Retries go through Action Scheduler when it is installed, WP-Cron otherwise. Any other answer is final, and redirects are never followed.

Each failed attempt adds one to the webhook’s count of failures in a row, and a 2xx answer sets it back to zero. At 50, Pro switches the webhook off, its waiting retries stop, the list shows it as Paused and the site admin gets an email. A webhook already past the limit is switched off when the Webhooks card lists it. Switching it back on starts the count again.

The Test button sends a webhook.test event at once. It fires the delivery hooks like a real attempt, but is never retried and never counted.

Check-in at the door

• Each scan calls POST /happenboard/v1/pro/checkin/mark with the ticket’s code, plus the event picked in Event at this door when there is one.
• A ticket code that fails verification gets HTTP 400 and counts towards the lockout (happenboard_pro_checkin_lockout).
• A genuine ticket is refused with HTTP 409 when it is for another event, when its booking holds no seat, or when it is for another date of a recurring event. That fires happenboard_pro_attendee_checkin_refused.
• An accepted scan fires happenboard_pro_attendee_checked_in, documented with the attendee hooks.
• The scanner’s Undo button deletes that check-in and fires happenboard_pro_attendee_checkin_undone.

The filters that shape the event sent to Google and Outlook are documented with the event hooks.

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; // Delivered.
        }
        // This hook also fires for 3xx, 4xx and 5xx answers.
        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 retries on its own: alert once, on the third failure in a row.
        $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 ) {
        // Our CRM has long maintenance windows: give it more room.
        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 already emails the site admin: tell the developer too.
        wp_mail(
            '[email protected]',
            'Webhook switched off',
            sprintf(
                'Webhook #%d failed %d times in a row and was switched off. Fix the receiver, then switch it back on in 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 ) {
        // Also accept our Mattermost incoming webhooks.
        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 ) {
        // Take back the entry our own door counter added at 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' ),
            'Check-in scanner locked',
            sprintf(
                '%s was locked out of check-in for 5 minutes after %d invalid codes.',
                $user ? $user->display_name : 'An unknown user',
                $count
            )
        );
    },
    10,
    2
);

apply_filters( 'happenboard_badges_per_sheet', int $per_sheet )

add_filter(
    'happenboard_badges_per_sheet',
    function ( $per_sheet ) {
        // Generous server: fewer, larger PDF files.
        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; // Also fires with '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 ) {
        // Skipped dates are already listed. Also keep our members-only dates
        // off Google, stored as UTC starts such as 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 ) {
        // Log only: Pro is already pushing this event back to 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 ) {
        // Log only: Pro is already pushing this event back to 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 ) {
        // Keep offering the front desk account (user 12) even when its
        // calendar cannot be read; every other host stays blocked.
        return array( 12 ) === array_values( $hosts ) ? false : $blocks;
    },
    10,
    2
);

Next steps

• Outbound webhooks: how site owners add webhooks and choose their events.
• Slack notifications: the Slack card that the URL filter applies to.
• Attendees and sign-up hooks: the check-in action and the other attendee events webhooks are built on.