In this section we guide you through the creation of your first webhook subscription on our API.

To create your first webhook with the Defacto API we will:

Create a webhook subscription on the Defacto REST API
Create a new invoice for it to trigger a status update
Look at the received the webhook notification

1. Create your first webhook subscription

The first step should be the creation of an endpoint on your own REST API.
However, to make this first test simpler and shorter, you can use webhook.site. It generates a callback URL specifically for you.

Copy "Your unique URL".

Create your first webhook subscription with POST /webhooks. For this example select the two event_types: Invoice.SUBMITTED and Invoice.VERIFIED and paste the URL from webhook.site in the to_url field.

2. Create a new invoice for it to trigger a status update

Generate a new invoice with the invoice generator at POST /sandbox/invoice-generator (use the curl command to get the full response)
Create the invoice with POST /invoices

3. Look at the received the webhook notification

Go back to webhook.site.

If you lost the link to your subscription, you can get it back by fetching your webhook subscriptions with GET /webhooks.

You should see two notifications. Here are the most important things to note:

There is one for Invoice.SUBMITTED and one for Invoice.VERIFIED
We call the POST method on the URL ➜ so when you will create your webhooks callbacks, make sure they listen to the POST method
The content uses the following data schema:

{
  "entity_type": "invoice",
  "transition_name": "SUBMIT",
  "status": "SUBMITTED",
  "timestamp": "2022-02-11T11:26:59.631326+00:00",
  "id": "a18d5057-0092-4555-b865-7ade03c3ac9b",
  "event_type": "Invoice.SUBMITTED",
  "entity_state": "<THE SAME PAYLOAD AS RETURNED BY THE GET ENDPOINT RETURNING THIS RESOURCE>"
}

Next steps

You can now create webhooks callbacks on your HTTP API. Do not forget that you must listen to the POST HTTP method.

You can create as many webhook subscription as you want. So, you can for example:

Create a single webhook callback
Create one webhook callback per status change
Create one webhook callback per type of resource

👍
You can also use our webhooks to get live Slack notifications!

What’s Next

What’s Next