Webhooks enable you to get live status updates
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!