Appointment booking hooks

happenboard_booking_approved

Action Free Since 1.0 src/Service/Booking/BookingService.php

Signature

do_action( 'happenboard_booking_approved', int $booking_id )

Parameters

$booking_id int

Booking primary key.

Return value

void

Example

add_action(
    'happenboard_booking_approved',
    function ( $booking_id ) {
        acme_notify_ops( 'Booking approved', $booking_id );
    }
);

Notes

• happenboard_booking_confirmed fires immediately after, so anything that only cares that a booking is now real should listen there instead and it will catch every path.
• Approving twice is refused before this fires, so a listener never sees the same booking approved more than once.

happenboard_booking_cancelled

Action Free Since 1.0 src/REST/Bookings.php

Signature

do_action( 'happenboard_booking_cancelled', int $booking_id )

Parameters

$booking_id int

Primary key of the cancelled booking in the happenboard_bookings table.

Example

add_action(
    'happenboard_booking_cancelled',
    function ( $booking_id ) {
        $repository = new \HappenBoard\Service\Booking\BookingRepository();
        $booking    = $repository->find_by_id( (int) $booking_id );
        if ( null === $booking ) {
            return;
        }

        error_log( sprintf(
            'Booking %d cancelled (host %d, start %s)',
            (int) $booking['booking_id'],
            (int) $booking['host_user_id'],
            (string) $booking['start_utc']
        ) );
    }
);

Notes

• There is no docblock on either call, so the auto-extracted signature shows no arguments. That is wrong: one argument is passed.
• Two call sites, same single argument. BookingService::cancel_by_token() serves DELETE /happenboard/v1/bookings/{token}, and REST\Bookings::admin_update() serves PATCH /happenboard/v1/bookings/{id} with status=cancelled. Handle both.
• Only the ID is passed. If you need the customer, host or start time, read the row yourself with BookingRepository::find_by_id(); it is already saved with the new status.
• The action fires only after the repository reports the UPDATE succeeded, so a failed cancellation (HTTP 500) never reaches your callback.
• The free plugin listens at priority 10 (BookingNotifier::on_cancelled): it sends the cancellation email and clears the booking’s pending reminders. A callback at a lower priority that throws will prevent both.

happenboard_booking_confirmed

Action Free Since 1.0 src/Service/Booking/BookingService.php

Signature

do_action( 'happenboard_booking_confirmed', int $booking_id )

Parameters

$booking_id int

Primary key returned by the insert.

Example

add_action(
    'happenboard_booking_confirmed',
    function ( $booking_id ) {
        $booking = ( new \HappenBoard\Service\Booking\BookingRepository() )
            ->find_by_id( (int) $booking_id );
        if ( null === $booking ) {
            return;
        }

        update_user_meta(
            (int) $booking['host_user_id'],
            'my_last_confirmed_booking',
            (int) $booking_id
        );
    }
);

Notes

• There is no docblock, so the auto-extracted signature lists no arguments. One argument is passed.
• Unlike happenboard_booking_created it carries only the ID, not the saved row. Read the row with BookingRepository::find_by_id() if you need it.
• Nothing in HappenBoard or HappenBoard Pro listens on it. It exists purely as an extension seam, which also means no other callback is competing with you on priority.
• Do not read it as “payment received”. Rows are always inserted with status confirmed, and a priced booking type gets payment_status = on_site in the free create path, never pending_payment.
• If you only need one hook, prefer happenboard_booking_created: it fires first, on the same code path, and hands you the row.

happenboard_booking_created

Action Free Since 1.0 src/Service/Booking/BookingService.php

Signature

do_action( 'happenboard_booking_created', int $booking_id, array<string,mixed> $data )

Parameters

$booking_id int

Primary key of the inserted row.

$data array<string,mixed>

The persisted row, re-read with SELECT *: booking_id, booking_type_id, host_user_id, customer_user_id, customer_email, customer_name, customer_tz, start_utc, end_utc, status, quantity, payment_status, order_id, custom_fields (JSON string), rescheduled_from, cancel_token, created_utc, updated_utc.

Example

add_action(
    'happenboard_booking_created',
    function ( $booking_id, $data ) {
        // $data is the raw DB row: it contains cancel_token. Never forward
        // the whole row to a third party.
        $payload = array(
            'id'       => (int) $booking_id,
            'start'    => (string) ( $data['start_utc'] ?? '' ),
            'host'     => (int) ( $data['host_user_id'] ?? 0 ),
            'quantity' => (int) ( $data['quantity'] ?? 1 ),
        );

        wp_remote_post(
            'https://example.com/crm/bookings',
            array(
                'timeout' => 5,
                'body'    => wp_json_encode( $payload ),
                'headers' => array( 'Content-Type' => 'application/json' ),
            )
        );
    },
    10,
    2
);

Notes

• Two arguments: register with add_action( ..., 10, 2 ).
• $data contains cancel_token, the 64-character secret that lets anyone cancel or reschedule the booking through the public REST routes. The submit response deliberately never returns it. Do not log the row, mail it, or forward it to a third party.
• The row comes from $wpdb->get_row( ..., ARRAY_A ), so every column arrives as a string, including booking_id and quantity. Cast before comparing, and note that custom_fields is still JSON-encoded.
• $data is (array) $saved. If the read-back fails, $saved is null and you receive an empty array, not a row with empty values. Guard on the keys you use.
• The free plugin listens at priority 10 (BookingNotifier::on_created): confirmation email with an .ics attachment, then reminder scheduling. The docblock says Pro listens here for payment, calendar write and SMS/WhatsApp, but no code in HappenBoard Pro registers a callback on this hook.

happenboard_booking_declined

Action Free Since 1.0 src/Service/Booking/BookingService.php

Signature

do_action( 'happenboard_booking_declined', int $booking_id )

Parameters

$booking_id int

Booking primary key.

Return value

void

Example

add_action(
    'happenboard_booking_declined',
    fn ( $booking_id ) => acme_log( 'declined', $booking_id )
);

Notes

• happenboard_booking_cancelled fires immediately after, which is what sends the cancellation email.

happenboard_booking_paid

Action Free Since 1.0 src/Service/Booking/BookingService.php

Signature

do_action( 'happenboard_booking_paid', int $booking_id )

Parameters

$booking_id int

Booking primary key.

Return value

void

Example

add_action(
    'happenboard_booking_paid',
    fn ( $booking_id ) => acme_issue_receipt( $booking_id )
);

Notes

• happenboard_booking_confirmed fires immediately after, on purpose: an extension that already subscribes to “this booking is now real” should not have to learn a second name because the money arrived by card.
• Payment providers deliver webhooks at least once and retry, so a booking that is already confirmed is treated as a success with nothing left to do. This action does not fire twice for one appointment.

happenboard_booking_payment_abandoned

Action Free Since 1.0 src/Service/Booking/BookingService.php

Signature

do_action( 'happenboard_booking_payment_abandoned', int $booking_id )

Parameters

$booking_id int

Booking primary key.

Return value

void

Example

add_action(
    'happenboard_booking_payment_abandoned',
    fn ( $booking_id ) => acme_metrics( 'checkout_abandoned', $booking_id )
);

Notes

• Abandoning a checkout is not a cancellation the customer should hear about, since they never had a booking. happenboard_booking_cancelled deliberately does not fire, so no cancellation email goes out.

happenboard_booking_payment_pending

Action Free Since 1.0 src/Service/Booking/BookingService.php

Signature

do_action( 'happenboard_booking_payment_pending', int $booking_id )

Parameters

$booking_id int

Booking primary key.

Return value

void

Example

add_action(
    'happenboard_booking_payment_pending',
    fn ( $booking_id ) => acme_metrics( 'checkout_started', $booking_id )
);

Notes

• Named _payment_pending, not _awaiting_payment, which is the filter above. WordPress keeps actions and filters in one namespace, so the two cannot share a name.

happenboard_booking_requested

Action Free Since 1.0 src/Service/Booking/BookingService.php

Signature

do_action( 'happenboard_booking_requested', int $booking_id )

Parameters

$booking_id int

Booking primary key.

Return value

void

Example

add_action(
    'happenboard_booking_requested',
    function ( $booking_id ) {
        wp_mail( get_option( 'admin_email' ), 'New booking request', 'Booking #' . $booking_id . ' is waiting.' );
    }
);

Notes

• happenboard_booking_confirmed deliberately does not fire for a request: a booking still waiting on your answer is not confirmed, and listeners on that seam must not act as though it were.
• happenboard_booking_created fires first, for every booking whatever its status.

happenboard_booking_rescheduled

Action Free Since 1.0 src/Service/Booking/BookingService.php

Signature

do_action( 'happenboard_booking_rescheduled', int $booking_id, string $old_start, string $new_start )

Parameters

$booking_id int

Primary key of the moved booking.

$old_start string

The previous start_utc, read from the row before the update. UTC Y-m-d H:i:s, or '' when the column was empty.

$new_start string

The new start, normalized to UTC Y-m-d H:i:s. The end time is derived from the booking type’s duration and is not passed.

Example

add_action(
    'happenboard_booking_rescheduled',
    function ( $booking_id, $old_start, $new_start ) {
        // Both timestamps are UTC 'Y-m-d H:i:s'.
        $old = new DateTimeImmutable( $old_start, new DateTimeZone( 'UTC' ) );
        $new = new DateTimeImmutable( $new_start, new DateTimeZone( 'UTC' ) );

        error_log( sprintf(
            'Booking %d moved from %s to %s (site time)',
            (int) $booking_id,
            $old->setTimezone( wp_timezone() )->format( 'Y-m-d H:i' ),
            $new->setTimezone( wp_timezone() )->format( 'Y-m-d H:i' )
        ) );
    },
    10,
    3
);

Notes

• Three arguments: register with add_action( ..., 10, 3 ). There is no docblock, so the auto-extracted signature lists none at all.
• Both timestamps are bare UTC Y-m-d H:i:s strings with no offset suffix. The customer’s own timezone stays in the row’s customer_tz column.
• The host is not reassigned. reschedule() never calls the assignment strategy, so host_user_id keeps its original value even if that host is not among the hosts free at the new time.
• The reschedule path checks that the new slot is offered but, unlike creation, never compares capacity_left against the booking’s quantity. A group booking can be moved onto a slot with fewer seats left than it needs.
• Reachable only from PATCH /happenboard/v1/bookings/{token}/reschedule. The admin route PATCH /happenboard/v1/bookings/{id} supports cancellation only, so an admin-side move does not exist yet and cannot fire this.