MerchantsRun your shop
Developer settings
Create applications and roll their secrets, set and verify the webhook URL, send a test event, redeliver webhooks and recover after a suspension.
Developers ("Applications, API keys and webhooks"), under Settings in the menu, is where you create the credentials your server uses and tell Fianto where to send webhooks. Each application has its own app ID and secret, and at most one webhook endpoint. What your server does with them is in Authentication and Webhooks.
Before you start
- Your account is approved.
- You know your password and have your authenticator app (or a recovery code): creating an application, rolling a secret and setting the webhook URL all ask for them.
- For a webhook: an
https://URL on your server that can answer Fianto's verification request.
Steps
Create an application
On Developers, click New application. Enter a New application name (1 to 100 characters), your Current password and an Authentication code or recovery code, then click Create application.
The application's app ID (fian_app_…) and secret (fian_sk_live_…) appear. "Copy this secret now.
You will not see it again." Store it on your server, never in a browser.
Roll a secret when you need a new one
On the application's page, under API keys, use Roll secret. Choose when the current secret stops working, under "The current secret stops working": "Immediately", "In 1 hour" (preselected) or "In 24 hours". "Immediately" asks you to confirm first. Enter your password and code; the new secret is shown once. At most two secrets are valid at a time.
Set the webhook URL
In the application's Webhook panel, click Manage webhook. Under Endpoint, enter the Endpoint URL, your password and code, and click Save and verify.
The URL must use https, with no user name, password or # fragment, on port 443 or 1024 and
above, on a public address, and be at most 2,048 characters. Fianto then sends a signed
endpoint.verification request; your server must answer HTTP 200 with
{"challenge":"…"} (the value it received) within 5 seconds. Your current URL keeps receiving
events until the new one is verified.
Send a test event
Once the URL is verified, a Test panel appears. Click Send test event: "Test event queued. It
appears in the log below." A test.event then shows in the Delivery log.
Redeliver an event, if your server missed it
In the Delivery log, click Redeliver on a delivery that has finished ("Delivered", "Failed"
or "Cancelled"): "Queued again. It appears at the top of the log." A redelivery carries the same
webhook-id, so your server can still recognise a duplicate. Redelivery is only in the dashboard,
and needs a verified URL: while the URL is not verified, and on "Held" deliveries, there is no
Redeliver button.
Verify again after a suspension
After 5 deliveries in a row fail every attempt, Fianto switches the URL off: "Deliveries to this URL kept failing, so it was switched off. Fix your endpoint, then verify again." New and waiting deliveries show as "Held" (up to 10,000). Fix your server, then click Verify again. Once the URL is verified, held events from the last 90 days are sent automatically.
Events sent while no URL is verified are not delivered
Fianto keeps the events it publishes while no URL is verified, but never delivers them. Your server
can read them with GET /v1/events.
Disabling an application is permanent
Disable application, under Danger zone, asks "Disable this application? Its secrets stop working immediately, and it cannot be re-enabled." It also disables its webhook endpoint and cancels its pending deliveries.
Limits
| Limit | Value |
|---|---|
| Active applications | 10 |
| Applications in all, disabled ones included | 100 |
| Webhook endpoints per application | 1 |
| Test events per application | 10 an hour, shared with the API's test-event route |
| Redeliveries per application | 60 an hour |
| Verification attempts | 10 an hour per endpoint, 30 an hour per account |
Check it worked
The Webhook panel shows your URL with the status "Verified". After Send test event, the
Delivery log lists test.event as "Delivered".
Troubleshooting
| You see | Why | Fix |
|---|---|---|
| "Application limit reached. Disable an application you no longer use, or contact support." | You have 10 active applications, or 100 in all. | Disable one you no longer use (this frees an active place only), or write to support@fianto.xyz. |
| "Enter a full URL starting with https://" | The dashboard checked the URL before sending it: it is not a full https URL. | Enter the whole URL, starting with https://. |
| "Enter a full https:// URL on a public host (port 443 or 1024 and above)" | The URL breaks one of the URL rules. | Use an https URL on a public host, on port 443 or 1024 and above. |
| "Your endpoint did not answer within 5 seconds." | The verification request timed out. | Answer the verification request at once, then verify again. |
| "Your endpoint did not echo the challenge back." | The answer did not contain the challenge. | Answer HTTP 200 with the challenge value you received. |
| "Your endpoint answered with a redirect. Redirects are not followed." | The URL redirects. | Enter the final URL. |
| "Too many verification attempts. Try again in an hour." | Too many verification requests for this endpoint or your account. | Wait an hour. |
| "Too many test events or redeliveries for this application this hour. Try again later." | More than 10 test events or 60 redeliveries in an hour. | Try again later. |
| No Redeliver button on a delivery | The delivery is still "Queued", "Retrying" or "Held", or the URL is not verified. | Wait for it to finish, or verify the URL again. |
See also
Was this page helpful? Tell us