You can use webhooks to respond to events that happen during transactions. Webhooks, which are also known as callbacks or Instant Payment Notifications (IPN), are HTTP POST requests that ProcessOut makes to your web server whenever an event occurs. Each POST contains an ID value that is unique to the event. Your code can pass this ID to our API to retrieve the full details of the event and then respond to it. You might use the details to begin delivery of an item after a successful payment, for example.

ProcessOut can use many different payment gateways and each one will probably have its own native format for event notifications. Our API is designed to abstract over these different formats to provide simple and consistent event data, regardless of where it originates from. For ease of use, the data includes information about the transaction state associated with the event.

Prerequisites

You must enable your webhook endpoint URL in the dashboard to receive notifications. See our guide to configuring webhooks for more information.

Note that the data in the body of the POST request is always in JSON format, so you should make sure your server accepts this. Also, you should remove all CSRF protection from your webhook endpoints to receive notifications. Most frameworks and CMS enable such protection by default for security reasons, but it can block ProcessOut from making POST requests to your endpoints.

You might find it useful to queue events and process several of them at once rather than responding fully to each event as soon as it arrives. Doing this allows you to acknowledge events quickly during busy periods and then process them later when things are quieter.

Retries

ProcessOut will repeatedly retry failed webhook POST requests to ensure that transient failures or temporary periods of downtime do not result in lost webhooks. Retries are spaced over time using a partially non-deterministic exponential backoff based on Euler’s number. This means later retries have a long wait time between attempts.

We guarantee that ProcessOut will retry failed webhooks at least 12 times over a period of 3 days, with the final attempt between 48 and 72 hours after the first send attempt. Any webhooks that are not accepted within this window will be abandoned.

The table below presents the approximate intervals of subsequent retries:

Retry no.	Minimum time since 1st attempt	Maximum time since 1st attempt
0 (first attempt)	0 [s]	0 [s]
1	2 [s]	3 [s]
2	8 [s]	10 [s]
3	23 [s]	30 [s]
4	1 [m] 4 [s]	1 [m] 25 [s]
5	2 [m] 55 [s]	3 [m] 53 [s]
6	7 [m] 57 [s]	10 [m] 37 [s]
7	21 [m] 40 [s]	28 [m] 53 [s]
8	58 [m] 56 [s]	1 [h] 18 [m] 34 [s]
9	2 [h] 40 [m] 13 [s]	3 [h] 33 [m] 37 [s]
10	7 [h] 15 [m] 33 [s]	9 [h] 40 [m] 44 [s]
11	19 [h] 43 [m] 58 [s]	26 [h] 18 [m] [38]
12	53 [h] 38 [m] 25 [s]	71 [h] 31 [m] 13 [s]
13	--- (13th retry would exceed 3 days) ---	--- (13th retry would exceed 3 days) ---

📘
Important Considerations for Webhook Consumption
Webhook Ordering
Webhook delivery order isn't guaranteed. For instance, you might receive a webhook for acaptureevent before the corresponding webhook containing anauthorizedevent. Your system should be built to handle webhooks gracefully, regardless of the order they arrive in.
Webhook Delivery
We guarantee at-least-once delivery for webhooks, meaning you might receive the same webhook more than once. To ensure your data stays consistent and to prevent duplicate processing, your application must implement deduplication mechanisms for all webhooks you consume.

Custom URL per invoice

curl -X POST https://api.processout.com/invoices \
    -u test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x:key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB \
    -d customer_id="cust_LvjCcLOVe6iWn2aeCNhNmK7RbbG6K8XF" \
    -d name="Amazing item" \
    -d amount="4.99" \
    -d currency="USD" \
    -d webhook_url="https://superstore.com/webhooks"

var ProcessOut = require("processout");
var client = new ProcessOut(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x",
    "key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB");

client.newInvoice().create({
    customer_id:          "cust_LvjCcLOVe6iWn2aeCNhNmK7RbbG6K8XF",
    name:                 "Amazing item",
    amount:               "4.99",
    currency:             "USD",
    webhook_url:          "https://superstore.com/webhooks"
}).then(function(invoice) {
    //

}, function(err) {
    // An error occured

});

import processout
client = processout.ProcessOut(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB")

invoice = client.new_invoice().create({
    "customer_id":          "cust_LvjCcLOVe6iWn2aeCNhNmK7RbbG6K8XF",
    "name":                 "Amazing item",
    "amount":               "4.99",
    "currency":             "USD",
    "webhook_url":          "https://superstore.com/webhooks"
})

require "processout"
client = ProcessOut::Client.new(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB")

invoice = client.invoice.create(
    "customer_id":        "cust_LvjCcLOVe6iWn2aeCNhNmK7RbbG6K8XF",
    name:                 "Amazing item",
    amount:               "4.99",
    currency:             "USD",
    webhook_url:          "https://superstore.com/webhooks"
)

<?php
$client = new \ProcessOut\ProcessOut(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB");

$invoice = $client->newInvoice()->create(array(
    "customer_id"          => "cust_LvjCcLOVe6iWn2aeCNhNmK7RbbG6K8XF",
    "name"                 => "Amazing item",
    "amount"               => "4.99",
    "currency"             => "USD",
    "webhook_url"          => "https://superstore.com/webhooks"
));

import "github.com/processout/processout-go"

var client = processout.New(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB",
)

iv, err := client.NewInvoice().Create(processout.InvoiceCreateParameters{
    Invoice: &processout.Invoice{
        CustomerID:          processout.String("cust_LvjCcLOVe6iWn2aeCNhNmK7RbbG6K8XF"),
        Name:                processout.String("Amazing item"),
        Amount:              processout.String("4.99"),
        Currency:            processout.String("USD"),
        WebhookURL:          processout.String("https://superstore.com/webhooks"),
    },
})

Usage

Each webhook POST request from ProcessOut only contains the ID value of the associated event in the event_id field. Use this ID to fetch the full set of event data using our API.

The event_type allows you to filter received webhooks to update your system. The list of transaction events is available here.

Example of a received webhook

{
  "event_id":"ev_kHVj3R57mQBInbWwGy4co0235GTLIYTH",
  "event_type":"transaction.captured"
}

Consume webhooks

# Webhooks are not supported with cURL.

var ProcessOut = require("processout");
var client = new ProcessOut(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x",
    "key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB");

// req is filled with the decoded json data from the request body
client.newEvent().find(req["event_id"]).then(function(event) {
    // We may now access the event
    var data = event.getData();

    switch (data["name"]) {
    case "invoice.completed":
        // Successful payment
        break;
    case "invoice.pending":
        // Payment still needs some time to be processed
        break;
    // ...
    default:
        console.log("Unknown webhook action");
        return;
    }

}, function(err) {
    // An error occured, most likely the event was coming from an
    // untrusted source

});

import processout
client = processout.ProcessOut(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB")


# req is filled with the decoded json data from the request body
event = client.new_event().find(req["event_id"])
data  = event.data

if data["name"] == "invoice.completed":
    # Successful payment
    pass

elif data["name"] == "invoice.pending":
    # Payment still needs some time to be processed
    pass

# ...

else:
    # Shouldn't be here..
    print("Unknown webhook action")

require "processout"
client = ProcessOut::Client.new(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB")


# req is filled with the decoded json data from the request body
event = client.event.find(req.event_id)
data  = event.data

if data["name"] == "invoice.completed"
    # Successful payment
elsif data["name"] == "invoice.pending"
    # Payment still needs some time to be processed

# ...

else
    # Shouldn't be here..
    puts "Unknown webhook action"
end

<?php
$client = new \ProcessOut\ProcessOut(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB");

$reqRaw = trim(file_get_contents("php://input"));
$req    = json_decode($reqRaw, true);

$event = $client->newEvent()->find($req["event_id"]);
$data  = $event->getData();

switch($data["name"])
{
case "invoice.completed":
    // Successful payment
    break;
case "invoice.pending":
    // Payment still needs some time to be processed
    break;
// ...
default:
    echo "Unknown webhook action"; exit();
}

import "github.com/processout/processout-go"

var client = processout.New(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB",
)

// EventData is the definition of a ProcessOut Event data
type EventData struct {
    Name        string              `json:"name"`
    Sandbox     bool                `json:"sandbox"`
    Invoice     *processout.Invoice `json:"invoice"`
}

// ProcessOutWebhook is the definition of a ProcessOut webhook
type ProcessOutWebhook struct {
    EventID string `json:"event_id"`
}

func handleProcessOutWebhooks(w http.ResponseWriter,
    r *http.Request) {

    defer r.Body.Close()
    reqRaw, err := ioutil.ReadAll(r.Body)
    if err != nil {
        panic(err)
    }

    // Decode the webhook
    webhook := &ProcessOutWebhook{}
    json.Unmarshal(reqRaw, &webhook)

    // Fetching the associated event
    event, err := client.NewEvent().Find(webhook.EventID)
    if err != nil {
        // Webhook not found, most likely coming from an
        // insecure source
        w.WriteHeader(http.StatusBadRequest)
        return
    }

    e, _ := event.(EventData)
    switch e.Name {
    case "invoice.completed":
        // Successful payment

    case "invoice.pending":
        // Payment still needs some time to be processed

    // ...

    default:
        // Return an HTTP OK response so that unsuported
        // webhooks do not get sent again
        w.WriteHeader(http.StatusOK)
        return
    }
}