Webhook Subscription

Webhooks provide a powerful mechanism to notify clients about about asynchronous API lifecycle events.By configuring webhook endpoints, your platform can eliminate the need for constant API polling.

When and Why to Use Webhooks

Webhooks are particularly useful when an integrating partner needs to respond to an asynchronous event that occurs in the PCE system. For example, an integrating partner may want to be notified when a transaction fails for any reason.

How Webhooks work?

Webhooks utilize HTTP callbacks to send push notifications to pre-configured endpoints.
When an event related to a PCE entity occurs, a JSON payload containing details about the event is sent as a POST request to your specified webhook URL.

Acknowledging Requests

Given a valid and secure (HTTPS) URL, Plastiq Connect will dispatch an event via an HTTP call.

Subscribers, typically the integrating partner, will have up to 5 seconds to acknowledge that they have received the webhook payload by returning an HTTP status code of 200.

Note, webhooks are not sent in any sequence; thus, kindly pay attention to the webhook event timestamp.

Retry and Backoff Strategy

If the webhook client fails to acknowledge the event within 5 seconds (maybe because their system is down or overloaded), we will retry several times with an increasing time interval between attempts. This is done to ensure our clients receive event notifications reliably. The webhook system will attempt to retry a total of 5 times before the system will block the endpoint. You can re-enable the endpoint once the issue on your end is resolved.

❗️
Subscription deactivation
If you fail to acknowledge a webhook after 8 tries, your subscription will be disabled and you will no longer receive future webhook events. This is done to ensure we do not continue to send requests to a non-responsive / inactive client. You can re-enable the endpoint once the issue on your end is resolved.

How to Subscribe to Webhook Events

Webhook subscriptions are currently handled on an ad-hoc basis. Reach out to us to subscribe to webhook events for your integration.

Subscription Confirmation

Upon creation, a subscription confirmation message will be sent to the configured URL. This is a crucial step to verify ownership and readiness of your endpoint.

{
    "Type": "SubscriptionConfirmation",
    "MessageId": "e7caa54f-7380-42ff-bf41-1a847b5db5a9",
    "Token": "2336412f37fb687ff41a9668e",
    "TopicArn": "arn:aws:sns:us-east-1:9853074181:test-topic1",
    "Message": "You have chosen to subscribe to the topic arn:aws:sns:us-east-1:985323074181:test-topic1.\nTo confirm the subscription, visit the SubscribeURL included in this message.",
    "SubscribeURL": "https://sns.us-east-1.amazonaws.com/?Action=ConfirmSubscription&TopicArn=arn:aws:sns:us-east-1:985323074181:test-topic1&Token=2336440d7df41a9668e",
    "Timestamp": "2024-05-15T08:53:04.873Z",
    "SignatureVersion": "1",
    "Signature": "KwtRZ0gNGtkBIeMMzUkPVh/Ail3173vqyffdpebj1qHe1xVx0EOIM3tx3w==",
    "SigningCertURL": "https://sns.us-east-1.amazonaws.com/SimpleNotificationService-60eadc530605d63b8e62a523676ef735.pem"
}

Steps to Confirm Subscription

Extract SubscribeURL: From the received subscription confirmation message, extract the value of the SubscribeURL field.
Make a GET Call: Make an HTTP GET request to the extracted SubscribeURL. This action confirms your subscription and signals to PCE that your endpoint is ready to receive event notifications.

Handling Authentication for Webhook Endpoints If your configured webhook endpoint requires authentication (e.g., Basic Authentication), follow these additional steps when receiving the subscription confirmation message:

Return HTTP 401 (First Response): Upon receiving the SubscriptionConfirmation message, your endpoint should first return an HTTP 401 Unauthorized status code.
Include WWW-Authenticate Header: In the 401 response, include the WWW-Authenticate = Basic header. This indicates to the system that your endpoint requires Basic Authentication.
Proceed with GET Call toSubscribeURL: After sending the 401 response with the WWW-Authenticate header, proceed with making the GET call to the SubscribeURL as described above.

Once the subscription is successfully confirmed, you will begin receiving webhooks at your configured endpoint, typically within 1-1.5 hours.

Sample Code for Handling Subscription Confirmation The following Node.js example demonstrates how to handle SNS (Simple Notification Service) messages, including subscription confirmation and authentication. While the example uses x-amz-sns-message-type headers, the core logic for confirming the SubscribeURL and handling authentication remains relevant for PCE webhooks.

// Endpoint to handle SNS messages
app.post('/sns-endpoint', authMiddleware, (req, res) => {
    // Validate header (replace with your actual authentication logic)
    const authHeader = req.headers['authorization'];
    if (!authHeader) {
        res.setHeader('WWW-Authenticate', 'Basic');
        return res.status(401).send('Authentication required.');
    }

    // Handle SNS message type (adapt for PCE webhook message types if different)
    const messageType = req.headers['x-amz-sns-message-type']; // Or a similar header for PCE
    if (messageType === 'SubscriptionConfirmation') {
        // Handle subscription confirmation
        const confirmUrl = req.body.SubscribeURL;
        console.log(`Confirming subscription at URL: ${confirmUrl}`);

        // IMPORTANT: In a real application, you would make an HTTP GET request
        // to the confirmUrl to truly confirm the subscription.
        // For simplicity, this example just logs it.
        // Example using a library like 'axios' or 'node-fetch':
        // axios.get(confirmUrl)
        //   .then(() => console.log('Subscription confirmed successfully!'))
        //   .catch(error => console.error('Error confirming subscription:', error));

    } else if (messageType === 'Notification') {
        // Handle regular event notifications (adapt for PCE event types)
        const message = req.body.Message;
        console.log(`Received message: ${message}`);
        // Process the webhook payload based on the event type
    }

    // Acknowledge receipt of the message
    res.status(200).send('Message received.');
});

Best Practices

Acknowledge early

Sometimes, processing a webhook event can take time. Given that PCE webhook event timeouts will be retried automatically, it is important to acknowledge receipt of an event notification as early as possible to avoid processing the same event.

Acknowledge but ignore events you don't care about

There may be events you have registered for, but simply do not need to process. An example of such an event may be a specific Transaction Status notification that does not need further action.

In these cases, it is important to still return an HTTP 200 response, but simply discard the message to prevent PCE from unnecessarily resending you the same event.