Skip to main content

Webhooks

Learn how to get notified of any changes in your payments' data.

Webhooks allow your application to receive notifications when certain events occur. For example, when a payment status is updated, Dojo will make a POST request to your URL and let you know about it. You can create 1 webhook for each event. Use the Webhooks API to specify which events you would like to be notified about.

Every webhook from Dojo includes a dojo-signature header. You can use this to verify that the data is coming from Dojo.

Response handling​

When handling server code webhook calls, Dojo does the following:

  • Accepts any 2xx HTTP status code responses as a confirmation of successful delivery of the webhook message.
  • Interprets 4xx or 5xx HTTP status code responses as an error and re-attempts delivery for a limited number of times.

Create webhooks​

Use the following instructions to create webhooks by using our API. You can also manage webhooks in the Developer Portal.

To start using webhooks, you need:

  1. Choose which events to subscribe to.
  2. Enable the webhook using the webhook endpoint.
  3. Verify Dojo webhooks.
  4. Go live.

Before you start​

Before you begin, make sure you have followed the Getting started guide and get your API keys. Webhooks API use the same Basic Authentication as Dojo API. For the test environment, use your secret key with the prefix sk_sandbox_.

Step 1. Choose which events to subscribe to​

You can have a list of all events by sending a GET request to Dojo's webhooks endpoints.

GET /webhooks/events

We recommend subscribing to the payment_intent.status_updated event to receive updates on changes in the status of your payment intents. For a complete list of available events and their payloads, see Available webhooks.

Step 2. Enable the webhook​

You can turn on webhooks either via the developer portal (https://developer.dojo.tech) or using the APIs.

To enable a webhook using the API, use the endpoint below:

POST /webhooks

In your request, include:

  • events: the list of events you would like to subscribe to. For the list of the events, see Available webhooks.

  • url: the endpoint the Dojo servers will send notifications to. The endpoint must be accessible from the public internet for the webhook to work. It must be an HTTPS endpoint as well. If you want to test webhooks before you create or configure a live service, you can use one of several request logging sites, for example, WebHook Tester. Alternatively, use a service like ngrok.

Here's an example of how to subscribe to the payment_intent.status_updated event:

webhooks/curl/enable-webhooks.sh
loading...

For the full API specification, see the API reference.

Step 3. Verify Dojo webhooks​

To verify the authenticity of the webhook, you need to digest the received payload body by using HMAC-SHA256 with your secret.value as a key. If the result matches the one that you received in the dojo-signature header, then the webhook is authentic.

For example:

  • for the following request body payload:
warning

In order to do a proper calculation, the JSON in the example below needs to be formatted without any spaces or line breaks.

{
  "id": "evt_hnnHxIKR_Uy6bhZCusCltw",
  "event": "payment_intent.created",
  "accountId": "acc_test",
  "createdAt": "2022-02-01T13:07:41.8667859Z",
  "data": {
    "paymentIntentId": "pi_vpwd4ooAPEqyNAQe4z89WQ",
    "paymentStatus": "Created",
    "captureMode": "Auto"
    }
}

  • where the secret to calculate the signature was: PDYkJQq6sESYHp_zJuTTBQ

  • the signature header would be: sha256=4B-49-F8-FE-25-A7-E6-7D-00-4F-A7-9C-F8-0B-63-00-C7-77-B4-F2-2D-E5-E1-22-84-FA-04-18-50-A1-76-FD

Below is an example in C# to verify webhooks:

webhooks/python/verify-webhooks.py
loading...

Step 4. Go live​

If you want to test webhooks before you create or configure a live service, you can use one of several request logging sites, for example, WebHook Tester. Alternatively, use a service like ngrok.

When you are ready to go live, switch your secret key to production one with the prefix sk_prod_ and check url that you provide.

Available webhooks​

Payment intents webhooks​

  • payment_intent.status_updated

  • payment_intent.created

  • payment_intent.send-receipt

PropertyTypeDescription
idstringUnique identifier for the event.
eventstringThe event type. Possible values are payment_intent.status_updated, payment_intent.created, payment_intent.send-receipt.
accountIdstringUnique identifier for the account.
createdAtstring date-timeThe timestamp of the create date, in ISO 8601 UTC format.
dataobjectInformation regarding the payment.
data.paymentIntentIdstringUnique identifier for the payment intent.
data.paymentStatusstringCurrent status of the payment intent. Possible values are Created, Authorized, Captured, Reversed, Refunded, Canceled.
data.captureModestringThe type of capture for the payment. Possible values are Auto, Manual.

Webhooks and events management​

You can manage webhooks and events by using our API:

Last updated on