Webhooks

Registering a Webhook

curl "https://api.payload.co/webhooks/" \
    -u secret_key_3bW9JMZtPVDOfFNzwRdfE: \
    -d trigger="payment" \
    -d url="https://yourdomain.com/path/to/webhook/handler"

webhook = pl.Webhook.create(
    trigger='payment',
    url='https://yourdomain.com/path/to/webhook/handler'
)

webhook = Payload::Webhook.create(
    trigger: 'payment',
    url: 'https://yourdomain.com/path/to/webhook/handler'
)

<?php
$webhook = Payload\Webhook::create(array(
    'trigger' => 'payment',
    'url' => 'https://yourdomain.com/path/to/webhook/handler'
));
?>

const webhook = await pl.Webhook.create({
    trigger: 'payment',
    url: 'https://yourdomain.com/path/to/webhook/handler'
})

var webhook = await pl.Webhook.CreateAsync(new {
    trigger = "payment",
    url = "https://yourdomain.com/path/to/webhook/handler"
});

Webhooks can be used to monitor events in real-time by initiating an HTTP request to any specified url providing an instant notification of that event.

Webhooks are useful in a variety of use-cases. Workflows that are asynchronous are a great example of where a webhook can be very useful. Some asynchronous workflows include automatic payments that are triggered at a certain date, and time in the future, waiting for a resulting payment from a payment link, watching for live updates on the status of a processing account, or to monitor for rejected transactions.

See a full list of available webhooks

Webhook logs

Get webhook including logs

curl "https://api.payload.co/webhooks/wh_3c7SG8oGU0IkBW6bW0mpG" \
    -G \
    -u secret_key_3bW9JMZtPVDOfFNzwRdfE: \
    -d "fields=*,logs"

webhook = pl.Webhook.select('*', 'logs')\
    .get('wh_3c7SG8oGU0IkBW6bW0mpG')

webhook = Payload::Webhook.
    select('*', 'logs').
    get('wh_3c7SG8oGU0IkBW6bW0mpG')

<?php
$webhook = Payload\Webhook::seelct(['*', 'logs'])
    .get('wh_3c7SG8oGU0IkBW6bW0mpG');
?>

const webhook = await pl.select(pl.Webhook, pl.Webhook.logs)
    .get('wh_3c7SG8oGU0IkBW6bW0mpG')

var webhook = await pl.Webhook
    .Select("*", pl.Attr.logs)
    .GetAsync("wh_3c7SG8oGU0IkBW6bW0mpG");

Webhook-related issues can be tricky to debug because of their asynchronous nature. To get a full list of triggered webhook events, you can request the full webhook log that will include the date, time, url, type of trigger, object that generated the trigger and the resulting http status from the url.

{
    "object": "webhook_log",

    // The type of trigger
    "trigger": "payment",

    // The date and time of the trigger
    "created_at": "2021-07-07 23:19:32",

    // The object that triggered the webhook
    "triggered_on": {
        "id": "txn_3bW9JN4BVk3wU0ZZQs2Ay",
        "object": "transaction",
        "value": "processed"
    },

    // The resulting http status code from the url
    "http_status": 200,

    // The url that the webhook triggered
    "url": "https://example.com/example-webhook"
}