Kuinka toteuttaa custom webhook-ratkaisut WordPressissä

Webhookit ovat yksi tehokkaimmista tavoista integroida WordPress ulkoisiin järjestelmiin reaaliaikaisesti. Niiden avulla WordPress voi lähettää tai vastaanottaa tapahtumia ilman jatkuvaa pollingia tai raskaita integraatiokerroksia.

Hyvin rakennettu webhook-järjestelmä on:

• turvallinen
• skaalautuva
• retry-tuettu
• asynkroninen
• helposti monitoroitava

Huonosti toteutettu webhook taas aiheuttaa:

• timeoutteja
• duplicate eventtejä
• turvallisuusongelmia
• suorituskykyongelmia

Mitä webhook tarkoittaa

Webhook on HTTP-pyyntö, joka lähetetään automaattisesti tapahtuman yhteydessä.

Esimerkki:

Order Completed
↓
POST https://api.example.com/webhook

WordPress voi:

• lähettää webhookeja
• vastaanottaa webhookeja
• toimia molempina

Lähettävät webhookit WordPressissä

Tyypillinen flow:

Event → Queue → HTTP Request → External API

Esimerkki:

do_action('myplugin/order_completed', $order_id);

Webhook listener:

add_action('myplugin/order_completed', function($order_id) {

    wp_remote_post(
        'https://api.example.com/webhook',
        [
            'body' => json_encode([
                'order_id' => $order_id
            ]),
            'headers' => [
                'Content-Type' => 'application/json'
            ]
        ]
    );
});

Älä lähetä webhookeja synkronisesti

Huono malli:

User request → webhook → external API wait

Jos API hidastuu:

• frontend hidastuu
• request timeouttaa

Parempi:

Event → Queue → Background Worker → Webhook

Queue-pohjainen webhook-järjestelmä

Paras käytäntö:

wp_webhook_queue

Kentät:

• id
• payload
• status
• retries
• last_error
• created_at

Retry-logiikka

Webhookit epäonnistuvat joskus.

Tarvitset:

• retry count
• exponential backoff
• failed status

Esimerkki:

if ($response_failed) {

    $retry_after = time() + 300;
}

Idempotency

Webhook voi tulla useita kertoja.

Ratkaisu:

event_id
signature
processed_hash

Tarkista ettei sama eventti käsitellä kahdesti.

Webhook payload design

Hyvä payload:

{
  "event": "order.completed",
  "timestamp": 1710000000,
  "data": {
    "order_id": 123
  }
}

Tärkeää:

• versioitava
• selkeä schema
• metadata mukana

Signature validation

Pakollinen turvallisuuteen.

Lähettäjä:

$signature = hash_hmac(
    'sha256',
    $payload,
    $secret
);

Vastaanottaja:

hash_equals($expected, $received);

Webhook endpoint WordPressissä

Paras tapa:

register_rest_route(
    'myplugin/v1',
    '/webhook',
    [
        'methods' => 'POST',
        'callback' => 'handle_webhook'
    ]
);

Älä käytä admin-ajax webhookeihin

REST API on:

• kevyempi
• standardimpi
• helpompi suojata
• helpompi monitoroida

Webhook processing

Huono:

process_everything_immediately();

Parempi:

Receive webhook
↓
Validate
↓
Queue job
↓
Background process

Rate limiting

Webhook endpointit altistuvat abuse-kuormalle.

Tarvitset:

• rate limiting
• IP validation
• signature verification

Logging

Kaikki webhookit kannattaa logata:

logger()->info('Webhook received');

Tai custom table:

wp_webhook_logs

Webhook observability

Monitoroi:

• success rate
• retry rate
• latency
• failed requests
• queue size

Timeoutit

Älä käytä liian pitkiä timeoutteja:

'timeout' => 10

Liian pitkä timeout:

• jumittaa workerit
• kasvattaa queuea

Batch webhookit

Jos eventtejä tulee paljon:

Huono:

1000 webhook requestia

Parempi:

1 batch webhook

Webhook security

Tärkeää:

• HTTPS only
• HMAC signatures
• capability validation
• IP allowlist tarvittaessa
• replay protection

Replay protection

Lisää:

timestamp
nonce
signature

Ja tarkista:

• timestamp freshness

Async processing WordPressissä

Voit käyttää:

• WP-Cron
• Action Scheduler
• custom queue worker
• WP-CLI daemon

Webhook versionointi

Hyvä käytäntö:

v1/order.completed
v2/order.completed

Älä riko vanhoja integraatioita.

Dead-letter queue

Jos webhook epäonnistuu jatkuvasti:

failed_webhooks

Näin eventit eivät katoa.

Yleisimmät virheet

• webhook suoritetaan frontend-requestissa
• ei retry-logiikkaa
• ei signature validationia
• ei idempotencyä
• ei loggingia
• timeout liian pitkä
• ei queue-järjestelmää

Paras webhook-arkkitehtuuri

Moderni WordPress webhook stack:

• REST API endpointit
• queue-based processing
• async workers
• HMAC signatures
• retry + backoff
• observability + logging
• dead-letter queue
• idempotency protection
• batch processing tarvittaessa

Yhteenveto

Custom webhook-ratkaisut tekevät WordPressistä tehokkaan integraatioalustan, mutta vain jos ne rakennetaan asynkronisesti ja turvallisesti. Synkroniset webhookit ilman retry-logiikkaa tai signature validationia muuttuvat nopeasti suorituskyky- ja turvallisuusongelmaksi.

Kun webhookit toteutetaan queue-pohjaisesti, versioidusti ja monitoroitavasti, WordPress pystyy käsittelemään suuria määriä integraatiotapahtumia luotettavasti myös enterprise-ympäristöissä.