The canonical, always-current source for this reference is docs/hooks.md in the plugin’s repository; that file is the backward-compatibility contract. This page follows it closely, and exists so you can browse the extension surface and see worked examples without cloning the repo.
Anything prefixed approvaltrail_internal_ is not public and carries no compatibility guarantee. Don’t hook into it. (Two exist: approvaltrail_internal_schema_migrated and approvaltrail_internal_premium_booted.)
Actions
| Hook | Since | Arguments |
|---|---|---|
approvaltrail_booted |
0.1.0 | Plugin $plugin |
approvaltrail_proof_created |
0.1.0 | Proof $proof |
approvaltrail_proof_version_added |
0.1.0 | Proof $proof, ProofVersion $version |
approvaltrail_proof_approved |
0.1.0 | Proof $proof, ProofEvent $event |
approvaltrail_proof_changes_requested |
0.1.0 | Proof $proof, ProofEvent $event |
approvaltrail_proof_link_viewed |
0.1.0 | Proof $proof, ProofEvent $event |
approvaltrail_proof_expired |
0.1.0 | Proof $proof |
approvaltrail_production_lock_blocked |
0.1.0 | WC_Order $order, Proof $proof |
approvaltrail_production_lock_overridden |
0.1.0 | WC_Order $order, Proof $proof, string $reason |
Filters
| Hook | Since | Filters |
|---|---|---|
approvaltrail_approval_link_expiry |
0.1.0 | Link lifetime, in seconds |
approvaltrail_allowed_mime_types |
0.1.0 | Extension → MIME allow-list |
approvaltrail_max_upload_bytes |
0.1.0 | Maximum accepted upload size |
approvaltrail_email_recipients |
0.1.0 | Recipient addresses for a notification |
approvaltrail_production_lock_statuses |
0.1.0 | Guarded order statuses |
approvaltrail_proof_page_template |
0.1.0 | Approval-page template path |
approvaltrail_evidence_payload |
0.1.0 | Payload committed to the hash chain |
approvaltrail_retention_days |
0.1.0 | Days before a master file is released |
approvaltrail_certificate_data |
0.2.0 | Approval-record view model |
approvaltrail_certificate_template |
0.2.0 | Approval-record template path |
Scheduled actions
Run through Action Scheduler in the approvaltrail group. All handlers are idempotent and deduplicated, so they’re safe to re-trigger.
| Hook | Since | Arguments |
|---|---|---|
approvaltrail_send_notification |
0.1.0 | int $proof_id, int $event_id, string $kind |
approvaltrail_generate_preview |
0.2.0 | int $version_id |
approvaltrail_purge_masters |
0.2.0 | — |
Worked examples
Post to Slack when a proof is approved
add_action( 'approvaltrail_proof_approved', function ( $proof, $event ) {
wp_remote_post( 'https://hooks.slack.com/services/your/webhook/url', [
'body' => wp_json_encode( [
'text' => sprintf( 'Proof "%s" was approved on order #%d.', $proof->get_title(), $proof->get_order_id() ),
] ),
'headers' => [ 'Content-Type' => 'application/json' ],
] );
}, 10, 2 );Send the proof email to a second address
add_filter( 'approvaltrail_email_recipients', function ( $recipients, $proof ) {
$recipients[] = '[email protected]';
return $recipients;
}, 10, 2 );Keep master files forever on one site
add_filter( 'approvaltrail_retention_days', function () {
return 0;
} );Note: this can also be set directly in Settings with the same effect. The filter is for when you want the value computed, or want to override it without a settings-screen visit (for example, on a staging clone).
Add your shop’s logo to the approval record
add_filter( 'approvaltrail_certificate_data', function ( $data ) {
$data['logo_url'] = get_theme_mod( 'custom_logo_url' );
return $data;
} );Read the approval record article’s claim boundary before you touch the template — a customized record is still bound by the same rule ApprovalTrail’s own build enforces: it cannot say or imply “legally binding,” “e-signature,” “court-admissible,” “certified,” or “notarised.”
Accept a file type we don’t accept by default
add_filter( 'approvaltrail_allowed_mime_types', function ( $types ) {
$types['ai'] = 'application/postscript';
return $types;
} );Think of this as a security decision, not a convenience tweak. Every type you add here is a file type ApprovalTrail will now accept from an authenticated staff upload, so only add formats you understand the risk of.